ts2workflows 0.2.0 → 0.4.0

package/language_reference.md

@@ -40,6 +40,12 @@ It is not possible to construct a bytes object expect by calling a function that
 
 In addition to the literal `null`, the Typescript `undefined` value is also treated as `null` in Workflows YAML.
 
+### Implicit type conversions
+
+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 in an implicit conversion, such as `if (var) {...}`, results in a TypeError at runtime.
+
 ## Expressions
 
 Most Typescript expressions work as expected.
@@ -56,7 +62,7 @@ name === 'Bean'
 sys.get_env('GOOGLE_CLOUD_PROJECT_ID')
 ```
 
-Operators:
+## Operators
 
 | Operator     | Description                                  |
 | ------------ | -------------------------------------------- |
@@ -71,11 +77,59 @@ Operators:
 | &&, \|\|, !  | logical operators                            |
 | in           | check if a property is present in an object  |
 | ??           | nullish coalescing                           |
+| ?.           | optional chaining                            |
+| ? :          | conditional operator                         |
 
 The [precendence order of operators](https://cloud.google.com/workflows/docs/reference/syntax/datatypes#order-operations) is the same as in GCP Workflows.
 
 See [expression in GCP Workflows](https://cloud.google.com/workflows/docs/reference/syntax/expressions) for more information.
 
+### Conditional (ternary) operator
+
+The expression
+
+```javascript
+x > 0 ? 'positive' : 'not positive'
+```
+
+is converted to an [if() expression](https://cloud.google.com/workflows/docs/reference/stdlib/expression-helpers#conditional_functions):
+
+```yaml
+${if(x > 0, "positive", "not positive")}
+```
+
+⚠️ Note that Workflows always evaluates both expression branches unlike Typescript which evaluates only the branch that gets executed.
+
+### Nullish coalescing operator
+
+The expression
+
+```javascript
+x ?? 'default value'
+```
+
+is converted to a [default() expression](https://cloud.google.com/workflows/docs/reference/stdlib/expression-helpers#conditional_functions):
+
+```yaml
+${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`.
+
+### Optional chaining
+
+The optional chaining expression
+
+```javascript
+data.user?.name
+```
+
+is converted to a [map.get() expression](https://cloud.google.com/workflows/docs/reference/stdlib/map/get):
+
+```yaml
+${map.get(data, ["user", "name"])}
+```
+
 ## Template literals
 
 Template literals are strings that support string interpolation. For example, `Hello ${name}`.
@@ -145,7 +199,7 @@ is converted to an [assign step](https://cloud.google.com/workflows/docs/referen
       - projectId: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
 ```
 
-This syntax can be used to call [standard library functions](https://cloud.google.com/workflows/docs/reference/stdlib/overview), subworkflows or connectors.
+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.
 
@@ -175,7 +229,7 @@ main:
           severity: INFO
 ```
 
-Some Workflows standard library functions have names that are reserved keywords in Typescript. Those functions must be called with alternative names in ts2workflows source code:
+Some Workflows standard library functions have names that are reserved keywords in Typescript. Those functions must be called with alternative syntax in ts2workflows source code:
 
 - To generate a call to `default()` in Workflows code, use the nullish coalescing operator `??`.
 - To generete a call to `if()` in Workflows code, use the ternary operator `a ? b : c`.
@@ -307,38 +361,6 @@ steps:
       return: ${b}
 ```
 
-## Conditional (ternary) operator
-
-The expression
-
-```javascript
-x > 0 ? 'positive' : 'not positive'
-```
-
-is converted to an [if() expression](https://cloud.google.com/workflows/docs/reference/stdlib/expression-helpers#conditional_functions):
-
-```yaml
-${if(x > 0, "positive", "not positive")}
-```
-
-⚠️ Note that Workflows always evaluates both expression branches unlike Typescript which evaluates only the branch that gets executed.
-
-## Nullish coalescing operator
-
-The expression
-
-```javascript
-x ?? 'default value'
-```
-
-is converted to an [default() expression](https://cloud.google.com/workflows/docs/reference/stdlib/expression-helpers#conditional_functions):
-
-```yaml
-${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`.
-
 ## Loops
 
 The fragment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts2workflows",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Transpile Typescript code to GCP Workflows programs",
   "homepage": "https://github.com/aajanki/ts2workflows",
   "repository": {
@@ -19,7 +19,25 @@
     "build:functionmetadata": "tsx scripts/generateBlockingFunctionMetadata.ts",
     "lint": "eslint src test scripts",
     "format": "prettier . --write",
-    "test": "mocha"
+    "test": "mocha",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "prettier --write",
+      "eslint"
+    ],
+    "test/**/*.ts": [
+      "prettier --write",
+      "eslint"
+    ],
+    "scripts/**/*.ts": [
+      "prettier --write",
+      "eslint"
+    ],
+    "*.md": [
+      "prettier --write"
+    ]
   },
   "bin": "./dist/cli.js",
   "files": [
@@ -46,6 +64,8 @@
     "@typescript-eslint/parser": "^8.0.0",
     "chai": "^5.1.1",
     "eslint": "^9.10.0",
+    "husky": "^9.1.6",
+    "lint-staged": "^15.2.10",
     "mocha": "^10.4.0",
     "prettier": "^3.2.5",
     "rimraf": "^5.0.10",
@@ -54,7 +74,6 @@
   },
   "dependencies": {
     "@typescript-eslint/typescript-estree": "^8.0.0",
-    "@typescript-eslint/utils": "^8.0.0",
     "commander": "^12.1.0",
     "typescript": "^5.0.0",
     "yaml": "^2.4.2"

package/types/global.d.ts

@@ -0,0 +1,116 @@
+export {}
+
+/// <reference no-default-lib="true"/>
+
+declare global {
+  // Minimal definition of Symbol.iterator required by the for-of statement
+  interface SymbolConstructor {
+    readonly iterator: unique symbol
+  }
+
+  var Symbol: SymbolConstructor
+
+  interface Iterator<T> {}
+
+  interface Iterable<T> {
+    [Symbol.iterator](): Iterator<T>
+  }
+
+  interface IterableIterator<T> extends Iterator<T> {
+    [Symbol.iterator](): IterableIterator<T>
+  }
+
+  interface Array<T> {
+    // Array member access
+    [n: number]: T
+
+    // Arrays can be iterated by the for-of statement
+    [Symbol.iterator](): IterableIterator<T>
+  }
+
+  interface ArrayConstructor {
+    isArray(arg: any): arg is any[]
+  }
+
+  var Array: ArrayConstructor
+
+  interface Boolean {}
+  interface CallableFunction {}
+  interface Function {}
+  interface IArguments {}
+  interface NewableFunction {}
+  interface Number {}
+  interface Object {}
+  interface RegExp {}
+  interface String {}
+
+  /**
+   * Utility types
+   * Copied from lib.es5.d.ts
+   */
+
+  /**
+   * Make all properties in T optional
+   */
+  type Partial<T> = {
+    [P in keyof T]?: T[P]
+  }
+
+  /**
+   * Make all properties in T required
+   */
+  type Required<T> = {
+    [P in keyof T]-?: T[P]
+  }
+
+  /**
+   * Make all properties in T readonly
+   */
+  type Readonly<T> = {
+    readonly [P in keyof T]: T[P]
+  }
+
+  /**
+   * From T, pick a set of properties whose keys are in the union K
+   */
+  type Pick<T, K extends keyof T> = {
+    [P in K]: T[P]
+  }
+
+  /**
+   * Construct a type with a set of properties K of type T
+   */
+
+  type Record<K extends keyof any, T> = {
+    [P in K]: T
+  }
+
+  /**
+   * Obtain the return type of a function type
+   */
+  type ReturnType<T extends (...args: any) => any> = T extends (
+    ...args: any
+  ) => infer R
+    ? R
+    : any
+
+  /**
+   * Exclude from T those types that are assignable to U
+   */
+  type Exclude<T, U> = T extends U ? never : T
+
+  /**
+   * Extract from T those types that are assignable to U
+   */
+  type Extract<T, U> = T extends U ? T : never
+
+  /**
+   * Construct a type with the properties of T except for those in type K.
+   */
+  type Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>
+
+  /**
+   * Exclude null and undefined from T
+   */
+  type NonNullable<T> = T & {}
+}

package/types/workflowslib.d.ts

@@ -161,9 +161,15 @@ export declare namespace http {
 }
 
 export declare namespace json {
-  function decode(data: bytes | string): object
+  function decode(data: bytes | string): unknown
   function encode(
-    data: string | number | boolean | unknown[] | Record<string, unknown>,
+    data:
+      | string
+      | number
+      | boolean
+      | unknown[]
+      | Record<string, unknown>
+      | null,
     indent?:
       | boolean
       | {
@@ -172,7 +178,13 @@ export declare namespace json {
         },
   ): bytes
   function encode_to_string(
-    data: string | number | boolean | unknown[] | Record<string, unknown>,
+    data:
+      | string
+      | number
+      | boolean
+      | unknown[]
+      | Record<string, unknown>
+      | null,
     indent?:
       | boolean
       | {
@@ -192,7 +204,7 @@ export declare namespace map {
   export function get<T, K extends string | string[]>(
     map: Record<string, T>,
     keys: K,
-  ): K extends string ? T : unknown
+  ): K extends string ? T | null : unknown
   export function merge<T, U>(
     first: Record<string, T>,
     second: Record<string, U>,
@@ -245,7 +257,7 @@ export declare namespace text {
     index: number
     match: string
   }[]
-  function match_regexp(source: string, regexp: string): boolean
+  function match_regex(source: string, regexp: string): boolean
   function replace_all(source: string, substr: string, repl: string): string
   function replace_all_regex(
     source: string,

package/dist/transpiler/asserts.d.ts

@@ -1,7 +0,0 @@
-export declare function assertType(node: {
-    type: string;
-}, expectedType: string): void;
-export declare function assertOneOfManyTypes(node: {
-    type: string;
-}, expectAnyOfTheseTypes: string[]): void;
-//# sourceMappingURL=asserts.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"asserts.d.ts","sourceRoot":"","sources":["../../src/transpiler/asserts.ts"],"names":[],"mappings":"AAEA,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAM7E;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACtB,qBAAqB,EAAE,MAAM,EAAE,GAC9B,IAAI,CAMN"}

package/dist/transpiler/asserts.js

@@ -1,11 +0,0 @@
-import { InternalTranspilingError } from '../errors.js';
-export function assertType(node, expectedType) {
-    if (node?.type !== expectedType) {
-        throw new InternalTranspilingError(`Expected ${expectedType}, got ${node?.type}`);
-    }
-}
-export function assertOneOfManyTypes(node, expectAnyOfTheseTypes) {
-    if (!expectAnyOfTheseTypes.includes(node?.type)) {
-        throw new InternalTranspilingError(`Expected ${expectAnyOfTheseTypes.join(' or ')}, got ${node?.type}`);
-    }
-}