Merge pull request #817 from xddq/add-typescript-example

add example for testing typescript code with vscode-js-debug

README.md

@@ -89,7 +89,7 @@ For detailed explanation of the `.vimspector.json` format, see the
     * [PHP](#php)
        * [Debug web application](#debug-web-application)
        * [Debug cli application](#debug-cli-application)
-    * [JavaScript, TypeScript, etc.](#javascript-typescript-etc)
+    * [JavaScript and TypeScript](#javascript-and-typescript)
     * [Java](#java)
        * [Hot code replace](#hot-code-replace)
        * [Usage with YouCompleteMe](#usage-with-youcompleteme)
@@ -217,7 +217,7 @@ There are 2 installation methods:
 ### Method 2: Using a plugin manager
 
 1. [Check the dependencies](#dependencies)
-1. See the plugin manager's docs and install the plugin  
+1. See the plugin manager's docs and install the plugin
    For Vundle, use:
 
    ```vim
@@ -557,7 +557,7 @@ Vimspector is not:
   aproach. This means that it can only provide essential/basic debugging
   features for a given language. This makes it convenient for everyday usage,
   but not ideal for power users or those with very precise or specific
-  requirements. See [motivation](#motivation) for more info. 
+  requirements. See [motivation](#motivation) for more info.
 
 ## Status
 
@@ -631,7 +631,7 @@ Copyright © 2018 Ben Jackson
 ## Sponsorship
 
 If you like Vimspector so much that you're wiling to part with your hard-earned
-cash, please consider donating to one of the following charities, which are 
+cash, please consider donating to one of the following charities, which are
 meaningful to the author of Vimspector (in order of preference):
 
 * [Hector's Greyhound Rescue](http://hectorsgreyhoundrescue.org)
@@ -795,7 +795,7 @@ request, then you will be asked to enter a PID (process ID) to attach to.
 To make this easier, Vimspector supplies a little utility for listing PIDs. It's
 like a very very simple clone of `ps` but works on all the supported platforms.
 See [its README](support/vimspector_process_list/README.md) for instructions on
-setting it up. 
+setting it up.
 
 Run `go build` in the `support/vimspector_process_list` directory to set it
 up.
@@ -805,7 +805,7 @@ by the current user by default.
 
 Alternatively (preferably), you can use a special form of variable expansion
 called `${PickProcess(\"binaryName\")}`. The version of this call will list all
-processes for the current user that match this binary name. 
+processes for the current user that match this binary name.
 
 For example:
 
@@ -1123,7 +1123,7 @@ the [breakpoints window](#breakpoints-window).
 
 Currently, instruction breakpoints are automatically cleared when the debug
 session ends. The reason for this is that the addresses can't be guaranteed to
-be valid for any other debug session. However, this may also change in future. 
+be valid for any other debug session. However, this may also change in future.
 
 ### Clear breakpoints
 
@@ -1296,7 +1296,7 @@ let g:ycm_semantic_triggers =  {
 * Dispplay disassembly around current PC
 * Step over/into/out by instruction (contextually, or using the WinBar)
 * `:VimspectorDisassemble`, `vimspector#ShowDisassembly()` or
-  `<Plug>VimspectorDisassemble` 
+  `<Plug>VimspectorDisassemble`
 
 [![Demo](https://asciinema.org/a/esEncAxP45CJmo8Em1sQtxRYe.svg)](https://asciinema.org/a/esEncAxP45CJmo8Em1sQtxRYe)
 
@@ -2118,34 +2118,47 @@ export XDEBUG_CONFIG="idekey=xdebug"
 php <path to script>
 ```
 
-## JavaScript, TypeScript, etc.
+## JavaScript and TypeScript
 
 * Node.js
 
-Requires:
+This uses [vscode-js-debug](https://github.com/microsoft/vscode-js-debug), the
+debugger that is used in vscode as well. For additional configurations, check
+the documentation [here](https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md).
 
-* `install_gadget.py --force-enable-node`
-* Options described here:
-  https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md
-* Example: `support/test/node/simple`, `support/test/node/multiprocess`
+To install vscode-js-debug, run `VimspectorInstall vscode-js-debug` from vim or
+run the install script `install_gadget.py --force-enable-node`. There are
+multiple examples which you can check out. Find them under
+`support/test/node/simple`, `support/test/node/multiprocess` and
+`support/test/node/typescript`. A typical configuration for debugging typescript
+looks like this:
 
 ```json
+
 {
   "configurations": {
-    "run": {
+    "run - js-debug": {
       "adapter": "js-debug",
-      "filetypes": [ "javascript", "typescript" ], // optional
+      "filetypes": [ "javascript", "typescript" ],
       "configuration": {
         "request": "launch",
-        "stopOnEntry": true,
-        "console": "integratedTerminal",
-        "program": "${workspaceRoot}/simple.js",
+        "program": "${workspaceRoot}/src/index.ts",
         "cwd": "${workspaceRoot}",
-        "type": "pwa-node" // this is the default, but see below
+        "stopOnEntry": false,
+        "type": "pwa-node"
+      },
+      // 'breakpoints' is an optional part. This is a way to configure exception
+      // breakpoints. You can leave this out or set as you prefer.
+      "breakpoints": {
+        "exception": {
+          "all": "N",
+          "uncaught": "N"
+        }
       }
     }
   }
 }
+
 ```
 
 `vscode-js-debug` supports a number of different "types" and can do some stuff
@@ -2637,7 +2650,7 @@ as it is a common requirement.
 In many cases you will want to rebuild your project before starting a new debugging
 session. Vimspector is not a task manager and implementing this functionality
 is out of the scope of this project. However, there are some strategies described in the
-[community wiki](https://github.com/puremourning/vimspector/wiki/Pre-launch-building-strategies) 
+[community wiki](https://github.com/puremourning/vimspector/wiki/Pre-launch-building-strategies)
 to achieve similar functionality.
 
 

support/test/node/typescript/.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+package-lock.json

support/test/node/typescript/.vimspector.json

@@ -0,0 +1,24 @@
+{
+  "configurations": {
+    "run - js-debug": {
+      "adapter": "js-debug",
+      "filetypes": [ "javascript", "typescript" ],
+      "configuration": {
+        "request": "launch",
+        "program": "${workspaceRoot}/src/index.ts",
+        "cwd": "${workspaceRoot}",
+        "stopOnEntry": false,
+        "type": "pwa-node"
+      },
+      // 'breakpoints' is an optional part. This is a way to configure exception
+      // breakpoints. You can leave this out or set as you prefer.
+      "breakpoints": {
+        "exception": {
+          "all": "N",
+          "uncaught": "N"
+        }
+      }
+    }
+  }
+}
+

support/test/node/typescript/README.md

@@ -0,0 +1,23 @@
+# Howto
+
+This example shows you how to use vimspector with
+[vscode-js-debug](https://github.com/microsoft/vscode-js-debug). For all
+available options see
+[here](https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md#node-launch).
+
+## Prerequisites
+
+- Have nodejs installed (was tested with 18 and 20).
+- Ensure you have vscode-js-debug installed, check installation guides for
+  nodejs of the vimspector repo on how to do so.
+- Install dependencies `npm i`.
+
+## Debugging
+
+- Build the project `npm run build`
+- Open the typescript file with vim `vim ./src/index.ts`
+- Set breakpoints at line 2 and 3 (standard key mapping is F9)
+- Run debugging (standard key mapping is F5)
+- Press F5 once again (you should see console log output)
+- Press F5 once again (you should see another console log output)
+- Done🎉

support/test/node/typescript/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "vimspector-typescript-test",
+  "author": "Pierre Dahmani <hi@pierre-dev.com>",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@tsconfig/node18": "2.0.0",
+    "typescript": "5.3.3",
+    "@types/node": "18.16.8"
+  }
+}

support/test/node/typescript/src/index.ts

@@ -0,0 +1,6 @@
+const main = () => {
+  console.log(new Date().toISOString() + " Debugging typescript with vimspector🎉")
+  console.log(new Date().toISOString() + " Done!")
+}
+
+main()

support/test/node/typescript/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "@tsconfig/node18/tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "outDir": "dist",
+    "sourceMap": true,
+    "baseUrl": "."
+  },
+  "include": ["src", "test"],
+  "exclude": ["dist", "bundle", "node_modules"]
+}
+