feat: ACNA-3098 - allow action invocation of ES Modules / Typescript (#87)

shazron · purplecabbage · web-flow · commit 98d4e2acbb60 · 2024-09-27T12:27:46.000-07:00
* use dist folder (webpacked action source)
* add ESM action, Typescript action
* fix jsdoc
* add eslint config
* support DUMP_PARAMS input
* add comment regarding ts-loader
* add source-map output for webpack, add .vscode/launch.json
* remove cached webpacked code
* use aio-lib-runtime to build the app
* add actions watcher
* update README
* fix unit tests
* mock actionsWatcher
* completed 100% coverage
* specify version of @adobe/aio-lib-runtime for buildActions emptyDist param
* run-dev tests code cleanup
* fixed actions-watcher tests leaks
* fix: require.cache cleanup, always build latest
* require aio-lib-runtime with optimized builds

---------

Co-authored-by: Jesse MacFadyen &lt;purplecabbage@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -7,22 +7,19 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Codecov Coverage](https://img.shields.io/codecov/c/github/adobe/aio-cli-plugin-app-dev/master.svg?style=flat-square)](https://codecov.io/gh/adobe/aio-cli-plugin-app-dev/)
 
-This command is a new way of looking at local development.
-This uses the approach of a simulator, rather than an emulator.
-
-<!-- toc -->
-* [aio-cli-plugin-app-dev](#aio-cli-plugin-app-dev)
-<!-- tocstop -->
+- This command is a new way of looking at local development. This uses the approach of a simulator, rather than an emulator.
+- Supports ESM, and TypeScript actions.
+- [App Builder Debugging Docs](https://developer.adobe.com/app-builder/docs/guides/development/#debugging)
 
 ## Commands
 <!-- commands -->
-* [`aio app dev`](#aio-app-dev)
+- [`aio app dev`](#aio-app-dev)
 
 ## `aio app dev`
 
 Run your App Builder app locally
 
-```
+```sh
 USAGE
   $ aio app dev [-v] [--version] [-o] [-e <value>]
 
@@ -48,6 +45,58 @@ By default the hostname will be `localhost` and the default port is `9080`. You
 
 The command will try to use the default port, if it is not available it will find an open port to use instead.
 
+## Visual Studio Code Webpack Debugging Support (Source Maps)
+
+To enable step-by-step debugging in Visual Studio Code for your webpacked code, you will have to add source map support by adding a [custom webpack config](https://developer.adobe.com/app-builder/docs/guides/configuration/webpack-configuration/).
+
+In the root of your project, add a `webpack-config.js` file:
+
+```javascript
+module.exports = {
+  devtool: 'inline-source-map'
+}
+```
+
+## TypeScript Support
+
+Install these node modules in your app:
+`npm install --save-dev ts-loader typescript`
+
+In the root of your project, add a `webpack-config.js` file:
+
+```javascript
+module.exports = {
+  devtool: 'inline-source-map',
+  module: {
+    rules: [
+      {
+        // includes, excludes are in tsconfig.json
+        test: /\.ts?$/,
+        exclude: /node_modules/,
+        use: 'ts-loader'
+      }
+    ]
+  }
+}
+```
+
+In the root of your project, add a `tsconfig.json` file:
+
+```json
+{
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "target": "ES6",
+    "module": "ES6",
+    "sourceMap": true
+  }
+}
+```
+
+There is a Visual Studio Code issue with TypeScript and inspecting variables by hovering your mouse over them:
+
+<https://github.com/microsoft/vscode/issues/221503>
+
 ## Contributing
 
 Contributions are welcomed! Read the [Contributing Guide](CONTRIBUTING.md) for more information.
diff --git a/e2e/test-project/.eslintrc.json b/e2e/test-project/.eslintrc.json
@@ -0,0 +1,10 @@
+{
+  "settings": {
+      "jsdoc": {
+          "ignorePrivate": true
+      }
+  },
+  "parserOptions": {
+      "ecmaVersion": "latest"
+  }
+}
diff --git a/e2e/test-project/.vscode/launch.json b/e2e/test-project/.vscode/launch.json
@@ -0,0 +1,31 @@
+{
+  "version": "0.3.0",
+  "configurations": [
+    {
+      "name": "App Builder: debug actions",
+      "type": "node-terminal",
+      "request": "launch",
+      "command": "aio app dev",
+      "skipFiles": [
+        "<node_internals>/**/*.js"
+     ]
+    }, {
+      "name": "App Builder: debug full stack",
+      "type": "node-terminal",
+      "request": "launch",
+      "command": "aio app dev",
+      "sourceMapPathOverrides": {
+        "/__parcel_source_root/*": "${webRoot}/*"
+      },
+      "skipFiles": [
+        "<node_internals>/**/*.js"
+     ],
+      "serverReadyAction": {
+        "pattern": "server running on port : ([0-9]+)",
+        "uriFormat": "https://localhost:%s",
+        "action": "debugWithChrome",
+        "webRoot": "${workspaceFolder}"
+      }
+    }
+  ]
+}
diff --git a/e2e/test-project/package.json b/e2e/test-project/package.json
@@ -17,6 +17,8 @@
     "regenerator-runtime": "^0.13.5"
   },
   "devDependencies": {
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.5.4",
     "@babel/core": "^7.8.7",
     "@babel/plugin-transform-react-jsx": "^7.8.3",
     "@babel/polyfill": "^7.8.7",
diff --git a/e2e/test-project/src/dx-excshell-1/actions/addNumbers/index.js b/e2e/test-project/src/dx-excshell-1/actions/addNumbers/index.js
@@ -32,7 +32,7 @@ async function addNumbers (params) {
     const sum = nums.reduce((accum, num) => accum + parseInt(num.trim(), 10), 0)
     return {
       payload: sum, // to be passed to other actions in the sequence as part of params
-      body: { 
+      body: {
         payload: sum // sent to the http client for a stand-alone call
       }
     }
diff --git a/e2e/test-project/src/dx-excshell-1/actions/esmAction/index.js b/e2e/test-project/src/dx-excshell-1/actions/esmAction/index.js
@@ -0,0 +1,26 @@
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * The main function.
+ *
+ * @param {object} params the parameters
+ * @returns {object} runtime response object
+ */
+export async function main (params) {
+  const response = {
+    statusCode: 200,
+    params,
+    body: 'you were successful with esm'
+  }
+  return response
+}
diff --git a/e2e/test-project/src/dx-excshell-1/actions/post-data/index.js b/e2e/test-project/src/dx-excshell-1/actions/post-data/index.js
@@ -1,4 +1,25 @@
-async function main(params) {
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * The main function.
+ *
+ * @param {object} params the parameters
+ * @returns {object} runtime response object
+ */
+async function main (params) {
+  if (params.DUMP_PARAMS) {
+    console.log('params', JSON.stringify(params, null, 2))
+  }
   const response = {
     statusCode: 200,
     body: {
@@ -7,4 +28,4 @@ async function main(params) {
   }
   return response
 }
-exports.main = main
+exports.main = main
diff --git a/e2e/test-project/src/dx-excshell-1/actions/post-raw-data/index.js b/e2e/test-project/src/dx-excshell-1/actions/post-raw-data/index.js
@@ -1,4 +1,26 @@
-async function main(params) {
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * The main function.
+ *
+ * @param {object} params the parameters
+ * @returns {object} runtime response object
+ */
+async function main (params) {
+  if (params.DUMP_PARAMS) {
+    console.log('params', JSON.stringify(params, null, 2))
+  }
+
   const response = {
     statusCode: 200,
     body: {
@@ -7,4 +29,4 @@ async function main(params) {
   }
   return response
 }
-exports.main = main
+exports.main = main
diff --git a/e2e/test-project/src/dx-excshell-1/actions/tsAction/index.ts b/e2e/test-project/src/dx-excshell-1/actions/tsAction/index.ts
@@ -0,0 +1,25 @@
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * The main function.
+ *
+ * @returns {object} runtime response object
+ */
+export function main(params: object) {
+  const response = {
+    statusCode: 200,
+    params,
+    body: 'you were successful with typescript'
+  }
+  return response
+}
diff --git a/e2e/test-project/src/dx-excshell-1/ext.config.yaml b/e2e/test-project/src/dx-excshell-1/ext.config.yaml
@@ -42,6 +42,7 @@ runtimeManifest:
           runtime: nodejs:18
           inputs:
             LOG_LEVEL: debug
+            DUMP_PARAMS: $DUMP_PARAMS
           annotations:
             final: true
         post-raw-data:
@@ -50,6 +51,7 @@ runtimeManifest:
           runtime: nodejs:18
           inputs:
             LOG_LEVEL: debug
+            DUMP_PARAMS: $DUMP_PARAMS
           annotations:
             final: true
         noAdobeAuth:
@@ -124,3 +126,19 @@ runtimeManifest:
             LOG_LEVEL: debug
           annotations:
             final: true
+        esmAction:
+          function: actions/esmAction/index.js
+          web: 'yes'
+          runtime: nodejs:18
+          inputs:
+            LOG_LEVEL: debug
+          annotations:
+            final: true
+        tsAction:
+          function: actions/tsAction/index.ts
+          web: 'yes'
+          runtime: nodejs:18
+          inputs:
+            LOG_LEVEL: debug
+          annotations:
+            final: true
diff --git a/e2e/test-project/src/dx-excshell-1/web-src/src/config.json b/e2e/test-project/src/dx-excshell-1/web-src/src/config.json
@@ -11,6 +11,8 @@
   "dx-excshell-1/throwsError": "https://localhost:9080/api/v1/web/dx-excshell-1/throwsError",
   "dx-excshell-1/noResponseObject": "https://localhost:9080/api/v1/web/dx-excshell-1/noResponseObject",
   "dx-excshell-1/actionIsNonWeb": "https://localhost:9080/api/v1/dx-excshell-1/actionIsNonWeb",
+  "dx-excshell-1/esmAction": "https://localhost:9080/api/v1/web/dx-excshell-1/esmAction",
+  "dx-excshell-1/tsAction": "https://localhost:9080/api/v1/web/dx-excshell-1/tsAction",
   "dx-excshell-1/nonWebSequence": "https://localhost:9080/api/v1/dx-excshell-1/nonWebSequence",
   "dx-excshell-1/sequenceWithAllActionsAvailable": "https://localhost:9080/api/v1/web/dx-excshell-1/sequenceWithAllActionsAvailable",
   "dx-excshell-1/sequenceWithActionThatThrowsError": "https://localhost:9080/api/v1/web/dx-excshell-1/sequenceWithActionThatThrowsError",
diff --git a/e2e/test-project/tsconfig.json b/e2e/test-project/tsconfig.json
@@ -0,0 +1,4 @@
+{
+  "include": ["src/dx-excshell-1/actions/tsAction"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/e2e/test-project/webpack-config.js b/e2e/test-project/webpack-config.js
@@ -1,7 +1,12 @@
-
 module.exports = {
+  devtool: 'source-map',
   module: {
     rules: [
+      {
+        test: /tsAction\/index.ts$/,
+        // includes, excludes are in tsconfig.json
+        use: 'ts-loader'
+      },
       {
         test: /syntaxidermist\/index.js$/,
         use: [
@@ -11,9 +16,9 @@ module.exports = {
               name: '__index.js',
               emitFile: true
             }
-          },
-        ],
-      },
-    ],
-  },
+          }
+        ]
+      }
+    ]
+  }
 }
diff --git a/package.json b/package.json
@@ -13,10 +13,11 @@
     "@adobe/aio-lib-core-config": "^5",
     "@adobe/aio-lib-core-logging": "^3",
     "@adobe/aio-lib-env": "^3",
-    "@adobe/aio-lib-runtime": "^6",
+    "@adobe/aio-lib-runtime": "^7.0.0",
     "@adobe/aio-lib-web": "^7",
     "@oclif/core": "^3",
     "chalk": "^4",
+    "chokidar": "^3.6.0",
     "connect-livereload": "^0.6.1",
     "execa": "^5.0.0",
     "express": "^4.18.2",
@@ -27,7 +28,8 @@
     "livereload": "^0.9.3",
     "lodash.clonedeep": "^4.5.0",
     "open": "^8.4.2",
-    "ora": "^5"
+    "ora": "^5",
+    "upath": "^2.0.1"
   },
   "devDependencies": {
     "@adobe/aio-lib-core-networking": "^5",
diff --git a/src/commands/app/dev/index.js b/src/commands/app/dev/index.js
diff --git a/src/lib/actions-watcher.js b/src/lib/actions-watcher.js
diff --git a/src/lib/run-dev.js b/src/lib/run-dev.js
diff --git a/test/__fixtures__/dist/my-package/successReturnAction-temp/index.js b/test/__fixtures__/dist/my-package/successReturnAction-temp/index.js
diff --git a/test/commands/app/dev/index.test.js b/test/commands/app/dev/index.test.js
diff --git a/test/lib/actions-watcher.test.js b/test/lib/actions-watcher.test.js
diff --git a/test/lib/run-dev.test.js b/test/lib/run-dev.test.js

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ async function addNumbers (params) {`
`32`	`32`	`const sum = nums.reduce((accum, num) => accum + parseInt(num.trim(), 10), 0)`
`33`	`33`	`return {`
`34`	`34`	`payload: sum, // to be passed to other actions in the sequence as part of params`
`35`		`- body: {`
	`35`	`+ body: {`
`36`	`36`	`payload: sum // sent to the http client for a stand-alone call`
`37`	`37`	`}`
`38`	`38`	`}`