Presets

现成的 dev、prod、json 日志默认值

用 preset 一行设好环境默认。显式 config / startup 字段永远覆盖 preset。

import { Elysia } from 'elysia'
import { createElogs } from '@eastgold15/elogs'

const app = new Elysia().use(
  createElogs({
    preset: 'prod',
    config: {
      service: 'api',
      logFilePath: './logs/app.log',
    },
  })
)

可用 preset

Preset	pino.prettyPrint	showContextTree	showStartupMessage	startupMessageFormat	autoRedact	requestId
`dev`	`true`	`true`	`true`	`"banner"`	—	—
`prod`	`false`	`false`	`false`	`"banner"`	`true`	`true`
`json`	`false`	`false`	`false`	`"banner"`	—	—

表里 — 表示 preset 没设,会沿用 Elogs 的默认(false / undefined)。

json 是给日志聚合器(Datadog、Loki、Elasticsearch)的最小配置 —— 关掉所有装饰性输出,JSON 行就是唯一 payload。下游需要按行解析 JSON、又不需要人类可读格式时用它。

覆盖示例

preset 给出基线,显式 config / startup 字段覆盖单个键:

import { createElogs } from '@eastgold15/elogs'

createElogs({
  preset: 'prod',
  config: {
    autoRedact: false,        // 覆盖 prod 的 true
    showContextTree: true,    // 单独开
  },
  startup: {
    show: true,               // 覆盖 prod 的 false
  },
})

程序化解析

resolveOptions(options) 是 Elogs 内部用的 merge 函数 —— 拿到 preset 默认值后,把显式 config 字段 shallow-merge 上去(对 pino / logFilter / logRotation / timestamp 做嵌套深合并)。想先看解析结果再传给 createElogs 时用:

import { resolveOptions } from '@eastgold15/elogs'

const options = resolveOptions({ preset: 'dev', config: { service: 'api' } })
// options.config.service === 'api'
// options.config.showStartupMessage === true (来自 dev preset)

行为跟直接传 createElogs() 完全一致 —— resolveOptions 已经在 createElogs 内部被调用过一次,显式调一次只是为了“先看一眼”。

自定义 preset

registerPreset(name, defaults) 在进程级注册一个 preset,跟内置 dev / prod / json 一样被 resolveOptions 查表。适合在 monorepo 里把“staging / edge / canary”等环境的默认值抽到一处,而不是每个项目复制粘贴 12 行 config。

import { registerPreset } from '@eastgold15/elogs'

registerPreset('staging', {
  pino: { prettyPrint: true },
  showContextTree: true,
  requestId: true,
  autoRedact: true,
  useColors: true,
})

const app = new Elysia().use(createElogs({ preset: 'staging' }))

规则

重复注册同名 preset 抛 Error("createElogs: preset \"<name>\" already registered") —— 防止 typo 静默覆盖。
name 必须是非空字符串。
defaults 的 schema 跟 ElogsConfig 完全一致,不做轻量校验(resolveOptions 阶段统一管 logRotation 之类)。
注册时机,放自己项目的初始化入口(比如 src/logging.ts)。不要在请求处理函数里注册 —— 重复抛错会让第一个请求 500。

调试用 API

import { listPresets, getPresetDefaults } from '@eastgold15/elogs'

console.log(listPresets())
// ['dev', 'prod', 'json', 'staging']

console.log(getPresetDefaults('staging'))
// { pino: { prettyPrint: true }, showContextTree: true, requestId: true, ... }

测试重置

单测之间清掉注册表用 __resetPresetRegistry()(注意连同内置 dev / prod / json 一起清掉,生产代码绝不能调):

import { __resetPresetRegistry } from '@eastgold15/elogs'

afterEach(() => {
  __resetPresetRegistry()
})

TypeScript 提示

preset 字段的提示仍是 'dev' | 'prod' | 'json',但运行时接受任意字符串。IDE 自动补全给内置,用户 preset 用 as 断言或 satisfies 收口:

createElogs({ preset: 'staging' as 'dev' | 'prod' | 'json' | 'staging' })