@happyvertical/logger

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 4.2万

Structured logging for HAVE SDK with signal adapter

原始使用文档
文档目录12 节
  1. Installation
  2. Basic Usage
  3. Environment Variable
  4. Log Levels
  5. Signal Adapter
  6. Sentry Adapter
  7. API Overview
  8. Factory
  9. Classes
  10. Types
  11. Custom Logger
  12. License

@happyvertical/logger

Structured logging for HAVE SDK with signal adapter integration and optional Sentry error tracking. Provides a Logger interface with four severity levels, a console implementation with level filtering, and adapters that convert SMRT framework signals into log entries or Sentry breadcrumbs/exceptions.

Installation

pnpm add @happyvertical/logger

# Optional: for Sentry integration
pnpm add @sentry/node

Depends on @happyvertical/utils. Optional peer dependency on @sentry/node (for the /sentry subpath).

Basic Usage

import { createLogger } from '@happyvertical/logger';

// Console logger with default 'info' level
const logger = createLogger(true);

logger.info('Application started');
logger.debug('Verbose detail'); // Not output (below 'info')
logger.warn('High memory usage', { memoryMB: 512 });
logger.error('Connection failed', { host: 'localhost', port: 5432 });

// Configure a specific level
const debugLogger = createLogger({ level: 'debug' });

// No-op logger — all calls discarded, zero overhead
const silent = createLogger(false);

Environment Variable

Set HAVE_LOGGER_LEVEL to debug, info, warn, or error. Applies when using createLogger(true) or createLogger({}). Explicit config takes precedence:

process.env.HAVE_LOGGER_LEVEL = 'debug';
const logger = createLogger(true); // uses 'debug' from env

const explicit = createLogger({ level: 'warn' }); // uses 'warn', ignores env

Log Levels

debug < info < warn < error — messages below the configured threshold are discarded.

const logger = createLogger({ level: 'warn' });
logger.debug('ignored');  // not output
logger.info('ignored');   // not output
logger.warn('output');    // output
logger.error('output');   // output

Output format: [LEVEL] message {"key":"value"}

Signal Adapter

LoggerAdapter converts SMRT framework signals into structured log entries:

import { createLogger, LoggerAdapter } from '@happyvertical/logger';

const logger = createLogger({ level: 'info' });
const adapter = new LoggerAdapter(logger);
// Register adapter with a signal bus to log operations automatically

Signal type mapping: start → debug, step → debug, end → info, error → error.

Sentry Adapter

The /sentry subpath routes signals to Sentry/GlitchTip. Requires @sentry/node as a peer dependency.

import { createSentryAdapter } from '@happyvertical/logger/sentry';

const adapter = createSentryAdapter({ category: 'myapp' });
// Register adapter with a signal bus

// Error signals → Sentry.captureException with scope tags
// Non-error signals → Sentry.addBreadcrumb for debugging trail

API Overview

Factory

FunctionDescription
createLogger(config)Returns a Logger — ConsoleLogger when enabled, no-op when false
createSentryAdapter(config?)Returns a SentryAdapter (from /sentry subpath)

Classes

ClassDescription
ConsoleLoggerLogger implementation with level filtering, writes to console.*
LoggerAdapterSignal adapter that converts signals to structured log messages
SentryAdapterSignal adapter that routes errors to Sentry and adds breadcrumbs

Types

TypeDescription
LoggerInterface with debug, info, warn, error methods
LogLevel'debug' | 'info' | 'warn' | 'error'
LoggerConfigboolean | { level?: LogLevel }
SignalSignal event from operation execution
SignalAdapterInterface for handling signals
SignalType'start' | 'step' | 'end' | 'error'
SentryAdapterConfig{ category?: string }

Custom Logger

Implement the Logger interface for custom backends:

import type { Logger } from '@happyvertical/logger';

class MyLogger implements Logger {
  debug(message: string, context?: Record<string, unknown>): void { /* ... */ }
  info(message: string, context?: Record<string, unknown>): void { /* ... */ }
  warn(message: string, context?: Record<string, unknown>): void { /* ... */ }
  error(message: string, context?: Record<string, unknown>): void { /* ... */ }
}

License

MIT

版本与发布记录

@happyvertical/logger 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/logger 的常见问题

@happyvertical/logger 是什么?

Structured logging for HAVE SDK with signal adapter

如何安装 @happyvertical/logger?

在项目目录运行 npm install @happyvertical/logger,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-logger-context,可以用 npx have-logger-context 直接运行。

@happyvertical/logger 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/logger 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/logger 可以商用吗?

@happyvertical/logger 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/logger 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/logger 在 2026/10/17 – 2026/11/15 这 30 天内被下载 41,777 次,日均约 1,393 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/logger 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。