npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/logger-core

v0.0.2

Published

Framework-agnostic logger core for LDesign

Readme

@composy/logger-core

@composy/logger-core 提供 LDesign 的框架无关日志能力,适合作为应用、库、CLI 或 engine 插件的底层日志运行时。

能力范围

  • 分级日志:trace / debug / info / warn / error / fatal
  • 统一日志管线:插件前置处理、过滤、历史缓冲、监听器、同步或异步传输
  • 可扩展传输器:console、storage、http、websocket、dev-bridge
  • 错误追踪:window.onerror、unhandledrejection、资源加载错误、可选控制台错误捕获
  • 性能监控:计时器、长任务监控、指标采样
  • Engine 接入:可直接注册到 packages/engine 的插件体系

目录约定

src
├─ engine           # Engine 插件与状态键(framework-agnostic)
├─ errors           # 错误追踪与面包屑管理
├─ formatters       # 日志输出格式化
├─ logger           # Logger 核心实现与工厂函数
├─ performance      # 性能监控与指标收集
├─ plugins          # Logger 插件(控制台拦截、性能监控)
├─ styles           # 控制台输出样式(主题、颜色、徽章)
├─ transports       # 日志传输器(控制台、HTTP、WebSocket、存储、开发桥接)
├─ types            # 核心类型定义(LogLevel、LogEntry、LogTransport 等)
└─ utils            # 通用工具函数(队列、缓冲区、对象池、压缩、脱敏等)

包结构原则

  • logger 是唯一的日志写入核心实现,其他框架适配包不能复制写入管线
  • engine/runtime.ts 负责 engine API 注册、状态同步和状态清理,Vue 等适配层必须复用这些 helper
  • utils/environment.ts 负责运行环境探测,运行时代码不直接读取 Node.js 全局 process
  • errors/stack-parser.ts 使用线性字符串解析,避免复杂正则在异常堆栈上产生回溯风险

类型安全

本包 零 any 类型,所有接口和函数均使用完整 TypeScript 类型定义。核心类型包括:

  • LogLevel — 日志级别枚举(TRACE=0 到 FATAL=50)
  • LogEntry — 完整日志条目接口,包含 id、时间戳、级别、消息、数据、错误、标签、上下文等字段
  • LogTransport — 传输器抽象接口,支持 write/writeBatch/flush/close
  • LoggerPlugin — 插件抽象接口,支持 install/init/destroy/beforeLog/afterLog/onError 钩子
  • ILogger — 日志器核心 API 接口,定义所有公共方法的完整类型

快速开始

import {
  createConsoleTransport,
  createHttpTransport,
  createLogger,
  LogLevel,
} from '@composy/logger-core'

const logger = createLogger({
  name: 'app',
  level: LogLevel.INFO,
  async: true,
  transports: [
    createConsoleTransport({ level: LogLevel.DEBUG }),
    createHttpTransport({
      url: '/api/logs',
      level: LogLevel.WARN,
      batchSize: 20,
      batchInterval: 3000,
    }),
  ],
})

logger.info('application started')
logger.error('request failed', new Error('network error'))
await logger.flush()

插件与扩展

import { createConsolePlugin, createLogger } from '@composy/logger-core'

const logger = createLogger({ name: 'app' })

logger.use(
  createConsolePlugin({
    interceptWarn: true,
    interceptError: true,
  })
)

Engine 用法

import { createLoggerEnginePlugin } from '@composy/logger-core/engine'

engine.use(
  createLoggerEnginePlugin({
    name: 'logger',
    level: 20,
    registerApi: true,
  })
)

如果 engine 外部已经有 logger 实例,可以直接注入并避免卸载时销毁:

import { createLogger, createLoggerEnginePlugin } from '@composy/logger-core'

const logger = createLogger({ name: 'shared-runtime' })

engine.use(
  createLoggerEnginePlugin({
    logger,
    destroyOnUnmount: false,
  })
)

安装后可通过 engine state 读取:

  • logger:instance
  • logger:config

也可以复用底层桥接函数:

import {
  clearLoggerEngineState,
  registerLoggerEngineApi,
  syncLoggerEngineState,
} from '@composy/logger-core/engine'

syncLoggerEngineState(engine, logger, { name: 'logger' })
registerLoggerEngineApi(engine, 'logger', '1.0.0', logger)
clearLoggerEngineState(engine)

模块详解

Logger 核心(logger/)

  • Logger 类实现完整的 ILogger 接口,统一管理插件、过滤器和传输链路
  • 支持子日志器(child())和上下文传播(withContext()、withTags())
  • 内置对象池(ObjectPool)和环形缓冲区(CircularBuffer),减少 GC 压力
  • 异步队列(AsyncQueue)支持批量处理、自动刷新、有界死信队列和消费回调取消订阅

传输器(transports/)

  • ConsoleTransport:浏览器/Node.js 控制台美化输出,支持主题切换
  • HttpTransport:批量上报,支持重试、优先级排序、Beacon API、自定义请求
  • WebSocketTransport:实时推送,支持自动重连、心跳保活、消息积压
  • StorageTransport:持久化到 localStorage/IndexedDB/内存,支持压缩和 TTL
  • DevBridgeTransport:开发模式下通过 WebSocket 连接到 launcher 工具

可靠性与隐私边界

  • OfflineQueue 会等待 IndexedDB/localStorage 初始化,串行化持久化操作,并通过 maxSize、maxRetries、retryBatchSize 控制容量和重试;onOnline() 返回取消订阅函数,destroy() 会清理监听器和定时器。
  • AsyncQueue.onFlush() 返回 disposer;自动重试只重试失败消费者,避免其他消费者重复处理同一批日志。retryDeadLetter() 会将死信重放给当前全部消费者,外部副作用应保持幂等;onDeadLetterFull() 支持异步持久化,回调异常不会中断队列。
  • sanitizeObject() 支持 maxDepth、maxArrayLength、循环引用和非法 Date 保护,并使用安全属性定义处理 __proto__ 等用户输入键。
  • ErrorTracker.captureError() 接受任意未知错误值;stop() 会恢复原始全局 handler,即使原值为 null 也不会遗留监听器。
  • WebSocket/HTTP/Storage 传输器的 close() 可等待已有缓冲完成;WebSocket 并发 close() 调用共享同一个 Promise。

错误追踪(errors/)

  • ErrorTracker 自动捕获 window.onerror、unhandledrejection、资源加载错误
  • 全局 handler 停止时只恢复仍由当前实例安装的函数,不会覆盖宿主或其他 tracker 在运行期间替换的 handler
  • BreadcrumbManager 记录用户操作序列,支持导航、点击、HTTP、控制台等类型
  • stack-parser 使用线性解析替代正则,安全处理 Chrome/Firefox/Safari 堆栈格式

脱敏与离线队列(utils/)

  • sanitizeObject() 支持 maxDepth 与 maxArrayLength,遇到循环引用、过深对象或过长数组时返回稳定占位值,避免日志数据无限递归。
  • OfflineQueue 支持 maxRetries、批量入队和 onOnline() 取消订阅;持久化操作按顺序执行,容量淘汰与内存队列保持一致。

性能监控(performance/)

  • PerformanceMonitor 自动收集导航计时、资源计时、长任务
  • MetricsCollector 管理计时、计数器和仪表盘指标
  • PerformanceTimer 提供精确的代码执行时间测量

性能设计

  • 创建日志时先使用对象池草稿对象,再复制为稳定快照
  • 历史记录与传输器都基于快照运行,避免对象复用带来的数据串改
  • AsyncQueue 满载淘汰最旧项时移动逻辑起点并定期压缩底层数组,避免逐条搬移队列剩余内容
  • 异步队列与批量传输可直接等待 Promise 类型传输器,便于接入远程上报
  • HttpTransport.close() 会解绑页面生命周期监听,避免长期页面中残留 transport 实例引用
  • WebSocketTransport.close() 即使刷新或序列化失败也会释放心跳、重连定时器和异步队列

开发命令

pnpm --filter @composy/logger-core type-check
pnpm --filter @composy/logger-core lint:check
pnpm --filter @composy/logger-core build
pnpm --filter @composy/logger-core test:run

构建产物

build 使用 @composy/builder,默认由 rolldown 打包。构建后的 postbuild 会校验并归一化 dist、es、esm、lib,其中 dist/index.min.js 是以 LDesignLoggerCore 为全局名生成的真实 UMD 压缩产物,不是未压缩文件的副本。

pnpm --filter @composy/logger-core build
node --experimental-strip-types scripts/index.ts workspace:check-package-outputs --cwd packages/logger --target core