Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gins3000/node-debugprotocol-client
A standalone node client for the VSCode Debug Adapter Protocol
https://github.com/gins3000/node-debugprotocol-client
Last synced: 3 months ago
JSON representation
A standalone node client for the VSCode Debug Adapter Protocol
- Host: GitHub
- URL: https://github.com/gins3000/node-debugprotocol-client
- Owner: gins3000
- License: mit
- Created: 2019-11-11T12:03:28.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-06-17T20:24:06.000Z (5 months ago)
- Last Synced: 2024-07-13T06:34:29.955Z (4 months ago)
- Language: TypeScript
- Size: 278 KB
- Stars: 9
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-star - node-debugprotocol-client
README
# node-debugprotocol-client
A standalone node client for the VSCode Debug Adapter Protocol
> This project is a work in progress and should be used in production only with caution! Breaking changes can and will be made.
There exist a lot of implementations of the [VSCode Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/), both serverside and clientside, but there don't seem to be a lot of standalone client implementations.
This repository hosts a standalone NodeJS client library for the Debug Adapter Protocol, maybe enabling smaller node-based IDEs to get a piece of that cake too.
## Targeted [vscode-debugprotocol](https://www.npmjs.com/package/vscode-debugprotocol) version
v1.50.1
## Features
- An abstract base client (`BaseDebugClient`)
- Use boilerplate methods to conveniently send requests, listen to events or handle reverse requests
- Await `Request`s to receive the `Response` or catch `ErrorResponses` as `Error`s
- Register convenient async reverse-request handlers
- Set log level (`Off`, `On` or `Verbose`)
- Stream-based implementation (`StreamDebugClient`)
- Connect with `stream.Readable` and `stream.Writable`
- Socket-based implementation (`SocketDebugClient`)
- Connect with `net.Socket`
## Usage example
Install to your node project:
```shell
npm install node-debugprotocol-client
```
Instantiate a socket client:
```ts
import { SocketDebugClient, LogLevel } from "node-debugprotocol-client";
// create a client instance
const client = new SocketDebugClient({
port: 12345,
host: "localhost",
logLevel: LogLevel.Verbose,
loggerName: "My Debug Adapter Client"
});
// connect
await client.connectAdapter();
```
Or a stream client, if you want to handle the streams yourself:
```ts
import { StreamDebugClient, LogLevel } from "node-debugprotocol-client";
// create a client instance
const client = new StreamDebugClient({
logLevel: LogLevel.Verbose,
loggerName: "My Debug Adapter Client"
});
const { reader, writer } = magicallyGetStreams();
// connect
client.connectAdapter(reader, writer);
```
Then just use the client:
```ts
// initialize first
await client.initialize({
adapterId: "java",
// ...
})
// tell the debug adapter to attach to a debuggee which is already running somewhere
// SpecificAttachArguments has to extend DebugProtocol.AttachRequestArguments
await client.attach({
// ...
});
// set some breakpoints
await client.setBreakpoints({
breakpoints: [
{ line: 1337 },
{ line: 42 },
// ...
],
source: {
path: "/path/to/file.java"
}
})
// listen to events such as "stopped"
const unsubscribable = client.onStopped((stoppedEvent) => {
if (stoppedEvent.reason === "breakpoint") {
// we hit a breakpoint!
// do some debugging
// continue all threads
await client.continue({ threadId: 0 });
}
});
// send 'configuration done' (in some debuggers this will trigger 'continue' if attach was awaited)
await client.configurationDone();
// ...
// Event subscriptions can be unsubscribed
unsubscribable.unsubscribe();
// disconnect from the adapter when done
client.disconnectAdapter();
```
## Build for development
```bash
git clone https://github.com/gins3000/node-debugprotocol-client.git
cd node-debugprotocol-client
npm install
# build:
npm run build
# or watch mode:
npm run start
```
The `npm run boilerplate:*` commands extract names and generate boilerplate methods from the vscode-debugprotocol package. This helps when accommodating for a new version of the protocol.
## Issues and Feature requests
Please create an issue if you find this useful (or useless ;_;) and have ideas, suggestions or issues!