# @ydbjs/debug

> Centralized debug logging for YDB JavaScript SDK

Latest version **6.0.5** (published 2025-11-04) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @ydbjs/debug
pnpm add @ydbjs/debug
yarn add @ydbjs/debug
bun add @ydbjs/debug
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 6.0.5 |
| Published | 2025-11-04 |
| First published | 2025-06-29 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.19.0 |
| Dependencies | 2 |
| Unpacked size | 9.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 82 |
| Author | YDB Team |
| Maintainers | ydb-platform |
| Keywords | ydb, debug, logging, sdk, typescript |

## Links

- npm: https://www.npmjs.com/package/@ydbjs/debug
- Repository: https://github.com/ydb-platform/ydb-js-sdk
- Homepage: https://github.com/ydb-platform/ydb-js-sdk#readme
- Issues: https://github.com/ydb-platform/ydb-js-sdk/issues
- npm.io page: https://npm.io/package/@ydbjs/debug

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ^4.4.0
- [supports-color](https://npm.io/package/supports-color.md) ^10.2.2

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 6.0.5 (latest) — 2025-11-04
- 6.0.0-alpha.29 (alpha) — 2025-06-29
- 6.0.4 — 2025-10-11
- 6.0.3 — 2025-10-11
- 6.0.2 — 2025-10-11
- 6.0.1 — 2025-10-11
- 6.0.0 — 2025-09-23
- 7.0.0-alpha.33 — 2025-09-08
- 6.0.1-alpha.32 — 2025-07-11
- 6.0.1-alpha.31 — 2025-07-09
- 6.0.1-alpha.30 — 2025-07-02

## README

# @ydbjs/debug

Centralized debug logging for YDB JavaScript SDK, inspired by Playwright's debug architecture.

## Features

- **Centralized logging**: Single logger instance with category-based organization
- **Color-coded output**: Different colors for different categories
- **Scoped loggers**: Create focused loggers for specific components
- **Standard debug interface**: Compatible with the popular `debug` package
- **TypeScript support**: Full type safety for log categories

## Quick Start

### Installation

```bash
npm install @ydbjs/debug
```

### Basic Usage Example

```typescript
import { loggers } from '@ydbjs/debug'

// Create a topic writer with debug logging
class TopicWriter {
  private dbg = loggers.topic.extend('writer')

  constructor(producerId: string) {
    this.dbg.log('creating writer with producer: %s', producerId)
  }

  async connect() {
    this.dbg.log('connecting to topic service')
    try {
      // ... connection logic
      this.dbg.log('connected successfully')
    } catch (error) {
      this.dbg.log('error during connection: %O', error)
      throw error
    }
  }

  write(message: Uint8Array) {
    if (this.dbg.enabled) {
      this.dbg.log('writing message, size: %d bytes', message.length)
    }
    // ... write logic
  }

  destroy(reason?: Error) {
    this.dbg.log('writer destroyed, reason: %O', reason)
  }
}
```

### Running with Debug Output

```bash
# Enable all YDB debug output
DEBUG=ydbjs:* node app.js

# Enable only topic-related debugging
DEBUG=ydbjs:topic:* node app.js

# Enable specific writer debugging
DEBUG=ydbjs:topic:writer node app.js
```

### Sample Output

```
ydbjs:topic:writer creating writer with producer: my-producer +0ms
ydbjs:topic:writer connecting to topic service +2ms
ydbjs:topic:writer connected successfully +45ms
ydbjs:topic:writer writing message, size: 1024 bytes +1ms
ydbjs:topic:writer writer destroyed, reason: Error: shutdown +2s
```

## Usage

### Basic Usage

```typescript
import { loggers } from '@ydbjs/debug'

// Use predefined category loggers
loggers.topic.log('starting topic writer for producer %s', producerId)
loggers.auth.log('refreshing token')
loggers.grpc.log('%s %s', method, status)
```

### Creating Scoped Loggers

```typescript
import { ydbLogger } from '@ydbjs/debug'

// Create a logger for a specific category and subcategory
let writerLogger = ydbLogger.createLogger('topic', 'writer')
writerLogger.log('writer initialized with producer %s', producerId)

// Extend an existing logger
let authLogger = loggers.auth.extend('metadata')
authLogger.log('fetching token from metadata service')
```

### Available Categories

- `api` - API calls and responses
- `auth` - Authentication and token management
- `grpc` - gRPC client operations
- `driver` - Driver lifecycle and connection management
- `discovery` - Service discovery
- `session` - Session management
- `query` - Query execution
- `topic` - Topic operations
- `tx` - Transaction operations
- `retry` - Retry logic
- `error` - Error handling
- `perf` - Performance metrics
- `error` - Error handling
- `perf` - Performance metrics

## Environment Variables

Enable debug logging using the `DEBUG` environment variable:

```bash
# Enable all YDB logging
DEBUG=ydbjs:* node app.js

# Enable specific categories
DEBUG=ydbjs:topic:*,ydbjs:auth:* node app.js

# Enable specific subcategories
DEBUG=ydbjs:topic:writer node app.js
```

## Integration with YDB SDK

This package is designed specifically for the YDB JavaScript SDK and provides consistent logging across all SDK components:

```typescript
// Different components using consistent debug categories
loggers.auth.log('token refreshed successfully')
loggers.grpc.log('POST /Ydb.Topic.StreamWrite OK')
loggers.driver.log('driver initialized with %d endpoints', 3)
loggers.session.log('created new session, active: %d', 5)
```

## Architecture

The debug system follows Playwright's centralized approach:

- **Single logger instance** (`YDBDebugLogger`) manages all debug output
- **Category-based organization** with predefined categories
- **Color coding** for visual distinction in terminal output
- **Efficient caching** of debug instances to avoid recreation

This approach provides better performance and consistency compared to creating individual debug instances throughout the codebase.

---
_Source: https://npm.io/package/@ydbjs/debug · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._