ts2workflows 0.9.0 → 0.11.0

package/language_reference.md

@@ -20,6 +20,14 @@ Semicolon can be used as optional statement delimitter.
 - Array: `[1, 2, 3]`
 - Map: `{temperature: -12, unit: "Celsius"}`
 
+The Typescript type alias `WorkflowsValue` (provided by `ts2workflows/types/workflowslib`) represents any valid Workflows value. Sample usage:
+
+```typescript
+import { WorkflowsValue } from 'ts2workflows/types/workflowslib'
+
+const x: WorkflowsValue = [1, 2]
+```
+
 ### Array type
 
 ⚠️ Arrays are not objects in GCP Workflows. In particular, methods like `[].map()` and `[].concat()` are not available.
@@ -46,7 +54,7 @@ Note that `null` and `undefined` still are distinct types on the type checking s
 
 Expressions that combine variables with operators such as `+`, `>`, `==` perform implict type conversions according to the [rules listed on GCP Workflows documentation](https://cloud.google.com/workflows/docs/reference/syntax/datatypes#implicit-conversions). For example, applying `+` to a string and a number concatenates the values into a string.
 
-⚠️ Checking if a variable is null or not must be done by an explicit comparison: `if (var != null) {...}`. Relying on an implicit conversion (`if (var) {...}` where `var` is not a boolean) results in a TypeError at runtime.
+⚠️ Checking if a variable is null or not must be done by an explicit comparison: `if (myVar != null) {...}`. Relying on an implicit conversion (`if (myVvar) {...}` where `myVar` is not a boolean) results in a TypeError at runtime.
 
 ## Expressions
 
@@ -156,6 +164,25 @@ String literals can include interpolated variables. The syntax is same as in Typ
 
 ⚠️ Interpolated values can (only) be numbers, strings, booleans or nulls. Other types will throw a TypeError at runtime.
 
+## Variable scopes
+
+Variable scopes are determined by the [GCP Workflows scoping rules](https://cloud.google.com/workflows/docs/reference/syntax/variables#variable-scope).
+
+Variables have function scope, that is they are available in the function where they are defined. Variables defined in `for` and `except` blocks are exceptions; they belong to a local scope of the block in which they are declared.
+
+⚠️ TypeScript has more strict scoping rules. In Typescript, variables declared with `let` or `const` are accessible only on the block in which they are declared (i.e. variable declared inside an if branch cannot be accessed after the if block ends). Programs written according to TypeScript scoping rules always produce valid GCP Workflows programs, too.
+
+Trying to read a variable before it is assigned causes a runtime error.
+
+⚠️ If variable is not initialized at declaration, its value is implicitly set to `null`. For example, the following program will return `null`. (Note that the sample is not valid as a TypeScript program. TypeScript compiler consideres variable `x` to be used before it is assigned.)
+
+```typescript
+function main(): void {
+  let x: number | null
+  return x
+}
+```
+
 ## Subworkflow definitions
 
 ts2workflows converts Typescript `function`s to subworkflow definitions.
@@ -694,24 +721,25 @@ If an exception gets thrown inside a try block, the stack trace in Workflows log
 
 ## 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` intrinsic function. It must be called immediately after a try-catch block. `retry_policy` is ignored elsewhere.
+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 `retry_policy` intrinsic function. It must be called inside a try block. `retry_policy` is ignored elsewhere. Only the first `retry_policy` in a try block has any effect.
 
 The arguments of `retry_policy` specify which errors are retried and how many times. The arguments can be either a policy provided by GCP Workflows or a custom retry policy as explained in the next sections.
 
-If an exception gets thrown in a try block and the retry policy covers the exception, the try block is executed again. Finally and catch blocks are run after possible retry attempts. The following sample retries `http.get()` if it throws an HTTP error and executes `sys.log('Error!')` and `closeConnection()` after retry attempts.
+If an exception gets thrown in a try block and the retry policy covers the exception, the try block is executed again. Finally and catch blocks are run if the try block keeps failing after all retry attempts have been used up. The following sample retries `http.get()` if it throws an HTTP error covered by `http.default_retry`. It logs `sys.log('Error!')` if the number of retry attempts exceed retry policy's maximum retry attempt count. `closeConnection()` is run always regardless of whether the HTTP request succeeded or failed.
 
 ```javascript
 import { http, retry_policy, sys } from 'ts2workflows/types/workflowslib'
 
 function main() {
   try {
+    retry_policy(http.default_retry)
+
     http.get('https://visit.dreamland.test/')
   } catch (err) {
     sys.log('Error!')
   } finally {
     closeConnection()
   }
-  retry_policy(http.default_retry)
 }
 ```
 
@@ -724,11 +752,12 @@ import { http, retry_policy } from 'ts2workflows/types/workflowslib'
 
 function main() {
   try {
+    retry_policy(http.default_retry)
+
     http.get('https://visit.dreamland.test/')
   } catch (err) {
     return 'Error!'
   }
-  retry_policy(http.default_retry)
 }
 ```
 
@@ -743,19 +772,20 @@ import { http, retry_policy } from 'ts2workflows/types/workflowslib'
 
 function main() {
   try {
+    retry_policy({
+      predicate: http.default_retry_predicate,
+      max_retries: 3,
+      backoff: {
+        initial_delay: 0.5,
+        max_delay: 60,
+        multiplier: 2,
+      },
+    })
+
     http.get('https://visit.dreamland.test/')
   } catch (err) {
     return 'Error!'
   }
-  retry_policy({
-    predicate: http.default_retry_predicate,
-    max_retries: 3,
-    backoff: {
-      initial_delay: 0.5,
-      max_delay: 60,
-      multiplier: 2,
-    },
-  })
 }
 ```
 
@@ -904,7 +934,7 @@ function retry_policy(
 ): void
 ```
 
-A retry policy can be attached to a `try`-`catch` block be calling `retry_policy` as the next statement after the `try`-`catch`. ts2workflows ignores `retry_policy` everywhere else except after a `try`-`catch`.
+A retry policy can be attached to a `try`-`catch` block by calling `retry_policy` inside the `try` block. ts2workflows ignores `retry_policy` everywhere else.
 
 See the section on [retrying errors](#retrying-on-errors).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts2workflows",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Transpile Typescript code to GCP Workflows programs",
   "homepage": "https://github.com/aajanki/ts2workflows",
   "repository": {
@@ -12,7 +12,7 @@
   "types": "dist/index.d.ts",
   "type": "module",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "rimraf dist && npm run build:functionmetadata && tsc",
@@ -20,6 +20,7 @@
     "lint": "eslint src test scripts",
     "format": "prettier . --write",
     "test": "mocha",
+    "test-coverage": "nyc mocha",
     "prepare": "husky && npm run build"
   },
   "lint-staged": {
@@ -61,25 +62,26 @@
     "@eslint/js": "^9.10.0",
     "@types/chai": "^5.0.1",
     "@types/mocha": "^10.0.6",
-    "@types/node": "^18",
+    "@types/node": "^20",
     "@types/ramda": "^0.30.2",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "chai": "^5.1.1",
     "eslint": "^9.10.0",
     "husky": "^9.1.6",
-    "lint-staged": "^15.2.10",
+    "lint-staged": "^16.1.2",
     "mocha": "^11.1.0",
+    "nyc": "^17.1.0",
     "prettier": "^3.2.5",
-    "rimraf": "^5.0.10",
-    "tsx": "^4.10.2",
+    "rimraf": "^6.0.1",
+    "tsx": "~4.19.4",
     "typescript-eslint": "^8.0.0"
   },
   "dependencies": {
     "@typescript-eslint/typescript-estree": "^8.0.0",
-    "commander": "^13.1.0",
-    "ramda": "^0.30.1",
-    "typescript": "^5.0.0",
+    "commander": "^14.0.0",
+    "ramda": "^0.31.3",
+    "typescript": "^5.4.0",
     "yaml": "^2.4.2"
   }
 }

package/types/workflowslib.d.ts

@@ -10,6 +10,28 @@ export interface bytes {
   readonly [__bytes_tag]: 'bytes'
 }
 
+// GCP Workflows data types
+export type WorkflowsValue =
+  | boolean
+  | number
+  | string
+  | bytes
+  | WorkflowsValue[]
+  | { [key: string]: WorkflowsValue }
+  | null
+
+type BooleanNumberStringListOrDict =
+  | boolean
+  | number
+  | string
+  | BooleanNumberStringListOrDict[]
+  | { [key: string]: BooleanNumberStringListOrDict }
+
+type HTTPQuery = Record<
+  string,
+  string | number | boolean | (string | number | boolean)[]
+>
+
 // GCP Workflows expression helpers
 
 export declare function double(x: string | number): number
@@ -19,19 +41,10 @@ export declare function keys(map: Record<string, unknown>): string[]
 export declare function len(
   value: unknown[] | Record<string, unknown> | string,
 ): number
-export declare function get_type(
-  value:
-    | boolean
-    | number
-    | string
-    | unknown[]
-    | Record<string, unknown>
-    | null
-    | bytes
-    | undefined,
-): string
+export declare function get_type(value: unknown): string
 
 // GCP Workflows standard library functions
+// https://cloud.google.com/workflows/docs/reference/stdlib/overview
 
 export declare namespace base64 {
   function decode(data: bytes, padding?: boolean): string
@@ -39,7 +52,7 @@ export declare namespace base64 {
 }
 
 export declare namespace events {
-  function await_callback<ResponseType = unknown>(
+  function await_callback<ResponseType = WorkflowsValue>(
     callback: {
       url: string
     },
@@ -80,15 +93,12 @@ export declare namespace http {
   export function default_retry_predicate_non_idempotent(
     errormap: Record<string, any>,
   ): boolean
-  function _delete<ResponseType = unknown>(
+  function _delete<ResponseType = WorkflowsValue>(
     url: string,
     timeout?: number,
-    body?: unknown,
+    body?: any,
     headers?: Record<string, string>,
-    query?: Record<
-      string,
-      string | number | boolean | (string | number | boolean)[]
-    >,
+    query?: HTTPQuery,
     auth?: Record<string, string>,
     private_service_name?: string,
     ca_certificate?: string,
@@ -97,14 +107,11 @@ export declare namespace http {
     code: number
     headers: Record<string, string>
   }
-  export function get<ResponseType = unknown>(
+  export function get<ResponseType = WorkflowsValue>(
     url: string,
     timeout?: number,
     headers?: Record<string, string>,
-    query?: Record<
-      string,
-      string | number | boolean | (string | number | boolean)[]
-    >,
+    query?: HTTPQuery,
     auth?: Record<string, string>,
     private_service_name?: string,
     ca_certificate?: string,
@@ -113,10 +120,10 @@ export declare namespace http {
     code: number
     headers: Record<string, string>
   }
-  export function patch<ResponseType = unknown>(
+  export function patch<ResponseType = WorkflowsValue>(
     url: string,
     timeout?: number,
-    body?: unknown,
+    body?: any,
     headers?: Record<string, string>,
     query?: Record<
       string,
@@ -130,15 +137,12 @@ export declare namespace http {
     code: number
     headers: Record<string, string>
   }
-  export function post<ResponseType = unknown>(
+  export function post<ResponseType = WorkflowsValue>(
     url: string,
     timeout?: number,
-    body?: unknown,
+    body?: any,
     headers?: Record<string, string>,
-    query?: Record<
-      string,
-      string | number | boolean | (string | number | boolean)[]
-    >,
+    query?: HTTPQuery,
     auth?: Record<string, string>,
     private_service_name?: string,
     ca_certificate?: string,
@@ -147,15 +151,12 @@ export declare namespace http {
     code: number
     headers: Record<string, string>
   }
-  export function put<ResponseType = unknown>(
+  export function put<ResponseType = WorkflowsValue>(
     url: string,
     timeout?: number,
-    body?: unknown,
+    body?: any,
     headers?: Record<string, string>,
-    query?: Record<
-      string,
-      string | number | boolean | (string | number | boolean)[]
-    >,
+    query?: HTTPQuery,
     auth?: Record<string, string>,
     private_service_name?: string,
     ca_certificate?: string,
@@ -164,16 +165,13 @@ export declare namespace http {
     code: number
     headers: Record<string, string>
   }
-  export function request<ResponseType = unknown>(
+  export function request<ResponseType = WorkflowsValue>(
     method: string,
     url: string,
     timeout?: number,
-    body?: unknown,
+    body?: any,
     headers?: Record<string, string>,
-    query?: Record<
-      string,
-      string | number | boolean | (string | number | boolean)[]
-    >,
+    query?: HTTPQuery,
     auth?: Record<string, string>,
     private_service_name?: string,
     ca_certificate?: string,
@@ -186,16 +184,9 @@ export declare namespace http {
 }
 
 export declare namespace json {
-  function decode(data: bytes | string): unknown
+  function decode(data: bytes | string): WorkflowsValue
   function encode(
-    data:
-      | string
-      | number
-      | boolean
-      | unknown[]
-      | Record<string, unknown>
-      | null
-      | undefined,
+    data: unknown,
     indent?:
       | boolean
       | {
@@ -204,14 +195,7 @@ export declare namespace json {
         },
   ): bytes
   function encode_to_string(
-    data:
-      | string
-      | number
-      | boolean
-      | unknown[]
-      | Record<string, unknown>
-      | null
-      | undefined,
+    data: unknown,
     indent?:
       | boolean
       | {
@@ -228,10 +212,10 @@ export declare namespace list {
 
 export declare namespace map {
   function _delete<T>(map: Record<string, T>, key: string): Record<string, T>
-  export function get<T, K extends string | string[]>(
-    map: Record<string, T>,
-    keys: K,
-  ): K extends string ? T | null : unknown
+  // map.get() with a string key, returns a property value or null
+  export function get<T>(map: Record<string, T>, keys: string): T | null
+  // map.get() with string[] key or non-object lookup, the return type is unknown
+  export function get(map: any, keys: string | string[]): WorkflowsValue
   export function merge<T, U>(
     first: Record<string, T>,
     second: Record<string, U>,
@@ -250,23 +234,23 @@ export declare namespace math {
 }
 
 export declare namespace retry {
-  function always(exception: unknown): void
+  function always(exception: any): void
   const default_backoff: {
     initial_delay: number
     max_delay: number
     multiplier: number
   }
-  function never(exception: unknown): void
+  function never(exception: any): void
 }
 
 export declare namespace sys {
   function get_env(name: string): string | null
   function get_env(name: string, default_value: string): string
   function log(
-    data?: number | boolean | string | unknown[] | object,
+    data?: BooleanNumberStringListOrDict,
     severity?: string,
-    text?: number | boolean | string | unknown[] | object,
-    json?: object,
+    text?: BooleanNumberStringListOrDict,
+    json?: Record<string, any>,
     timeout?: number,
   ): void
   function now(): number
@@ -456,9 +440,9 @@ export declare namespace googleapis {
       interface GoogleLongrunningOperation {
         done: boolean
         error?: Status
-        metadata?: Record<string, unknown>
+        metadata?: Record<string, any>
         name: string
-        response: Record<string, unknown>
+        response: Record<string, any>
       }
       interface GoogleLongrunningListOperationsResponse {
         nextPageToken?: string
@@ -476,7 +460,7 @@ export declare namespace googleapis {
         displayName: string
         labels: Record<string, string>
         locationId: string
-        metadata?: Record<string, unknown>
+        metadata?: Record<string, any>
         name: string
       }
       interface ListCollectionIdsRequest {
@@ -538,7 +522,7 @@ export declare namespace googleapis {
       }
       interface Status {
         code: number
-        details: Record<string, unknown>[]
+        details: Record<string, any>[]
         message: string
       }
       interface StructuredQuery {
@@ -751,5 +735,5 @@ export declare function retry_policy(
 
 export declare function call_step<T, A extends any[]>(
   func: (...args: A) => T,
-  arguments: Record<string, unknown>,
+  arguments: Record<string, any>,
 ): T

package/dist/ast/validation.d.ts

@@ -1,20 +0,0 @@
-import { WorkflowApp } from './workflows.js';
-export declare class WorkflowValidationError extends Error {
-    issues: WorkflowIssue[];
-    constructor(issues: WorkflowIssue[]);
-}
-export interface WorkflowIssue {
-    type: string;
-    message: string;
-}
-/**
- * Execute all syntax validators on a WorkflowApp app.
- *
- * Throws a WorkflowValidationError if there are errors.
- */
-export declare function validate(app: WorkflowApp, disabled?: string[]): void;
-/**
- * Returns all validator names.
- */
-export declare function validatorNames(): string[];
-//# sourceMappingURL=validation.d.ts.map

package/dist/ast/validation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/ast/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEzD,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,MAAM,EAAE,aAAa,EAAE,CAAA;gBAEX,MAAM,EAAE,aAAa,EAAE;CAMpC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAWD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,GAAE,MAAM,EAAO,GAAG,IAAI,CAexE;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC"}