winston-transport-debug-console/readme.md

A Winston transport that makes logs visible in inspector clients (like VS Code’s Debug Console) with support for fully inspectable objects.

<p align="center">
 <h1 align="center">winston-transport-debug-console</h1>
 <p align="center">
  <a href="https://www.npmjs.com/package/winston-transport-debug-console">
   <img src="https://img.shields.io/npm/v/winston-transport-debug-console.svg?style=flat-square" alt="npm version">
  </a>
  <a href="https://github.com/godbleak/winston-transport-debug-console/blob/main/LICENSE">
   <img src="https://img.shields.io/npm/l/winston-transport-debug-console.svg?style=flat-square" alt="license">
  </a>
  <br><br>
    <i>A Winston transport that makes logs visible in inspector clients (like VS Code’s Debug Console) with support for fully inspectable objects.</q>
</p>

---

## Why?

By default, Winston writes to `stdout`/`stderr`. When debugging in a Node inspector client (like VS Code's Debug Console) those logs either won't make it to the debug console, or you must use some other method to capture them (like `"outputCapture": "std"` in VS Code), even then, they'll appear as plain strings in the **Debug Console** — You will not get object inspection.

This transport uses Node’s [`inspector.console`](https://nodejs.org/api/inspector.html#inspectorconsole) API (based on the Chrome DevTools Protocol) to send logs directly to the inspector. The result:

- Logs show up in VS Code’s Debug Console (and Chrome DevTools, WebStorm, etc.)
- Objects remain **inspectable**, not stringified
- No duplication in the terminal — `inspector.console` does not touch `stdout`/`stderr`

---

## Install

```bash
npm install winston-transport-debug-console
```

---

## Usage

```ts
import { createLogger, format, transports } from "winston"
import { DebugConsole } from "winston-transport-debug-console"

const logger = createLogger({
    level: "debug",
    format: format.combine(format.timestamp(), format.errors({ stack: true }), format.splat()),
    transports: [
        // Show inspectable objects in VS Code Debug Console
        new DebugConsole(),

        // Keep pretty logs in the terminal too
        new transports.Console({
            format: format.combine(
                format.colorize(),
                format.timestamp(),
                format.printf(({ level, message, timestamp, ...meta }) => {
                    const extra = Object.keys(meta).length ? ` ${JSON.stringify(meta, null, 2)}` : ""
                    return `${timestamp} ${level}: ${message}${extra}`
                })
            ),
        }),
    ],
})

logger.info("User loaded", { id: 42, name: "Alice" })
```

In VS Code Debug Console, the `id` and `name` object are fully expandable.
In your terminal, you still see pretty, colored log lines.

### Logs show as originating from `debug-console-transport.js:35`?

If you see logs originating from `debug-console-transport.js:35` and you're using VS Code, you may need to set the following in your `launch.json`:

```json
"skipFiles": ["<node_internals>/**", "${workspaceFolder}/node_modules/**"]
```

---

## Options

```ts
new DebugConsole({
    level: "debug", // Winston's level filter (default: "info")
    levelMap: {
        // Optional map for custom levels
        crit: "error", // Map your "crit" level to inspector.console.error
        silly: "debug",
    },
})
```

- **`levelMap`**: Map unsupported Winston levels to existing inspector console methods.
  Throws if you try to use a level that isn’t supported and isn’t mapped.

---

## Node.js Compatibility

Requires **Node.js ≥ 11.0.0** (when `inspector.console` was introduced).
Tested on Node 18 and 20.

---

## License?

[MIT](./LICENSE)