@done-coding/output-core

环境无关的同构输出工具包核心库，提供统一的输出接口定义和混合类型实现。

功能特性

• 🌐 环境无关 - 可在任何 JavaScript 环境中使用（Node.js、浏览器、小程序等）
• 🔄 混合类型接口 - 支持函数调用和属性链式调用两种方式
• 📊 双模式输出 - 控制台输出和日志文件输出
• 🔇 动态静默控制 - 支持运行时动态控制输出静默，基于类型的条件静默
• 🔀 智能切换同步 - 支持输出目标间的智能切换和同步机制
• ⚡ 高性能 - 预计算枚举映射，优化的混合类型创建
• 🛡️ 完整类型支持 - 100% TypeScript 类型定义和类型推导
• 🔧 驱动注入模式 - 通过依赖注入支持不同平台的输出实现
• 📋 TABLE 类型特殊处理 - 智能表格数据展示和 JSON 序列化

快速开始

安装

npm install @done-coding/output-core
# 或
yarn add @done-coding/output-core
# 或
pnpm add @done-coding/output-core

最小可用示例

import {
  createOutputConsole,
  OutputConsoleTypeEnum,
  type OutputConsoleRaw,
} from "@done-coding/output-core";

// 自定义控制台输出实现
const consoleImpl: OutputConsoleRaw = (type, ...messages) => {
  console.log(`[${type}]`, ...messages);
};

// 创建输出实例
const output = createOutputConsole({
  outputImpl: consoleImpl,
});

// 使用输出实例
output.info("Hello World");
output.success("操作成功");
output.error("发生错误");

架构设计

分层架构

┌─────────────────────────────────────┐
│           适配包层                    │
│  (Node.js, Browser, UniApp, etc.)   │
├─────────────────────────────────────┤
│            核心包层                   │
│     (@done-coding/output-core)      │
├─────────────────────────────────────┤
│           驱动实现层                  │
│   (console.log, pino, custom, etc.) │
└─────────────────────────────────────┘

设计原则

1. 环境无关 - 核心逻辑不依赖特定环境，通过驱动注入支持多平台
2. 纯函数设计 - 所有核心函数都是纯函数，无副作用
3. 类型安全 - 完整的 TypeScript 类型定义，提供完整的类型推导
4. 高性能 - 预计算枚举映射，优化的数据结构
5. 可扩展性 - 支持自定义输出类型和处理逻辑
6. 极简 API - 最少化的公共 API，易于学习和使用

API 文档

枚举定义

OutputConsoleTypeEnum

控制台输出类型枚举（业务级，31-38）：

| 值 | 名称 | 说明 | | --- | ------- | -------- | | 31 | DEBUG | 调试信息 | | 32 | SKIP | 跳过 | | 33 | INFO | 提示信息 | | 34 | TABLE | 表格 | | 35 | STAGE | 步骤 | | 36 | SUCCESS | 成功 | | 37 | WARN | 警告 | | 38 | ERROR | 错误 |

OutputLogFileTypeEnum

日志文件输出类型枚举（系统级，对齐 Pino 标准，10-60）：

| 值 | 名称 | 说明 | | --- | ----- | ------------ | | 10 | TRACE | 跟踪级别 | | 20 | DEBUG | 调试级别 | | 30 | INFO | 信息级别 | | 40 | WARN | 警告级别 | | 50 | ERROR | 错误级别 | | 60 | FATAL | 致命错误级别 |

核心函数

createOutputConsole

创建控制台输出实例。

签名：

function createOutputConsole(
  options: CreateOutputConsoleOptions,
): OutputConsole;

参数：

| 参数 | 类型 | 默认值 | 说明 | | ----------------------- | ------------------------------------- | ------ | -------------------- | | options.outputImpl | OutputConsoleRaw | - | 输出实现函数（必传） | | options.isSilent | (type) => boolean | - | 动态静默控制函数 | | options.enableColor | boolean | true | 是否启用颜色输出 | | options.colorMap | Record<OutputConsoleTypeEnum, string> | - | 自定义颜色映射 | | options.isSwitchLogFile | (type) => boolean | - | 切换到日志文件的条件 | | options.isSyncToLogFile | (type) => boolean | - | 同步到日志文件的条件 | | options.outputFileFn | OutputConsoleRaw | - | 日志文件输出函数 |

返回值： OutputConsole 混合类型实例

createOutputLogFile

创建日志文件输出实例。

签名：

function createOutputLogFile(
  options: CreateOutputLogFileOptions,
): OutputLogFile;

参数：

| 参数 | 类型 | 默认值 | 说明 | | ----------------------- | ----------------- | ------ | -------------------- | | options.outputImpl | OutputLogFileRaw | - | 输出实现函数（必传） | | options.isSilent | (type) => boolean | - | 动态静默控制函数 | | options.logFilePath | string | - | 日志文件路径 | | options.isSwitchConsole | (type) => boolean | - | 切换到控制台的条件 | | options.outputConsoleFn | OutputLogFileRaw | - | 控制台输出函数 |

返回值： OutputLogFile 混合类型实例

类型定义

OutputConsoleRaw

type OutputConsoleRaw = (
  type: OutputConsoleTypeEnum,
  ...messages: unknown[]
) => void;

OutputConsole

type OutputConsole = OutputConsoleRaw & {
  debug: (...messages: unknown[]) => void;
  skip: (...messages: unknown[]) => void;
  info: (...messages: unknown[]) => void;
  table: (...messages: unknown[]) => void;
  stage: (...messages: unknown[]) => void;
  success: (...messages: unknown[]) => void;
  warn: (...messages: unknown[]) => void;
  error: (...messages: unknown[]) => void;
};

OutputLogFileRaw

type OutputLogFileRaw = (
  type: OutputLogFileTypeEnum,
  ...messages: unknown[]
) => void;

OutputLogFile

type OutputLogFile = OutputLogFileRaw & {
  trace: (...messages: unknown[]) => void;
  debug: (...messages: unknown[]) => void;
  info: (...messages: unknown[]) => void;
  warn: (...messages: unknown[]) => void;
  error: (...messages: unknown[]) => void;
  fatal: (...messages: unknown[]) => void;
};

进阶使用

自定义平台适配

// 浏览器环境适配
const browserConsoleImpl: OutputConsoleRaw = (type, ...messages) => {
  const styles = {
    [OutputConsoleTypeEnum.INFO]: "color: blue",
    [OutputConsoleTypeEnum.ERROR]: "color: red",
  };
  console.log(`%c${messages.join(" ")}`, styles[type] || "");
};

// 小程序环境适配
const miniProgramImpl: OutputConsoleRaw = (type, ...messages) => {
  wx.getLogManager().log(...messages);
};

// React Native 环境适配
const reactNativeImpl: OutputConsoleRaw = (type, ...messages) => {
  console.log(...messages);
};

切换和同步逻辑

const output = createOutputConsole({
  outputImpl: consoleImpl,
  // 错误级别切换到日志文件（不在控制台显示）
  isSwitchLogFile: (type) => type === OutputConsoleTypeEnum.ERROR,
  // 警告级别同步到日志文件（控制台和文件都显示）
  isSyncToLogFile: (type) => type === OutputConsoleTypeEnum.WARN,
  outputFileFn: (type, ...messages) => {
    // 这里需要将控制台类型映射到日志文件类型
    fileLogger(type, ...messages);
  },
});

output.info("普通信息"); // 只在控制台显示
output.warn("警告信息"); // 控制台和文件都显示
output.error("错误信息"); // 只在文件中记录

动态静默控制

const output = createOutputConsole({
  outputImpl: consoleImpl,
  // 动态控制静默：只在调试模式下显示 DEBUG 信息
  isSilent: (type) => {
    if (type === OutputConsoleTypeEnum.DEBUG) {
      return !process.env.DEBUG;
    }
    return false;
  },
});

output.debug("调试信息"); // 只在 DEBUG=true 时显示
output.info("普通信息"); // 总是显示

TABLE 类型处理

const output = createOutputConsole({
  outputImpl: consoleImpl,
});

// 数组表格
output.table([
  { name: "张三", age: 25 },
  { name: "李四", age: 30 },
]);

// 对象表格
output.table({
  total: 100,
  success: 95,
  failed: 5,
});

开发与测试

测试覆盖率

• 语句覆盖率: 100%
• 分支覆盖率: 98.03%
• 函数覆盖率: 100%
• 行覆盖率: 100%

本地开发

# 克隆仓库
git clone https://github.com/done-coding/output-core.git
cd output-core

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 运行测试
pnpm test

# 构建
pnpm build

贡献流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

常见问题

Q: Core 包和 Node 包的区别是什么？

A: Core 包提供统一的接口定义和混合类型实现，不依赖任何环境，需要手动传入 outputImpl 参数。Node 包基于 Core 包，自动提供 console.log + chalk 和 pino 的输出实现，无需手动传入 outputImpl。

Q: Node 包的 outputFileFn 参数类型是什么？

A: outputFileFn 的类型是 OutputConsoleRaw，因为它接收的是控制台类型参数，然后在内部进行类型映射后输出到日志文件。

Q: 如何在浏览器中使用？

A: 需要创建一个浏览器适配包，实现 OutputConsoleRaw 接口，然后使用 createOutputConsole 创建实例。

Q: 支持哪些 TypeScript 版本？

A: 支持 TypeScript 4.5+，完整的类型定义和类型推导。

Q: 如何自定义输出类型？

A: 可以扩展 OutputConsoleTypeEnum 和 OutputLogFileTypeEnum，然后实现对应的输出处理逻辑。

许可证

MIT