@vobs/logger 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @vobs/logger
+
+Structured, level-filtered logging with pluggable transports, context scoping, and default redaction.
+
+## Install
+
+```bash
+npm install @vobs/logger
+```
+
+## Quick start
+
+```ts
+import { createLogger, createMemoryTransport } from '@vobs/logger'
+
+const memory = createMemoryTransport(100)
+const logger = createLogger({
+  level: 'info',
+  context: { app: 'console' },
+  transports: [memory]
+})
+
+const request = logger.child({ requestId: 'request-1' })
+request.warn('request failed', { status: 503 })
+await logger.flush()
+```
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createLogger(options?: LoggerOptions): Logger` | Creates a logger; defaults to level `'info'` and a console transport. |
+| `logger.level: LogLevel` | Minimum level: `'debug'`, `'info'`, `'warn'`, or `'error'`. |
+| `logger.log(level, message, context?)` / `debug` / `info` / `warn` / `error` | Emit entries; below-level calls are dropped. |
+| `logger.child(context: LogContext): Logger` | Returns a logger whose entries merge the parent and child context. |
+| `logger.flush(): Promise<void>` | Waits for pending async writes, then calls `flush` on each transport. |
+| `logger.dispose(): void` | Stops the logger; the root logger also disposes owned transports. |
+| `createConsoleTransport(target?: ConsoleLike): LogTransport` | Writes `[level] message` plus context to a console-like target. |
+| `createMemoryTransport(limit?): MemoryLogTransport` | Keeps entries in a ring buffer with `entries` and `clear()`. |
+| `loggerPlugin(options?): VobsPlugin` | Provides the logger through `LOGGER_KEY`. |
+| `useLogger(): Logger` | Injects the logger inside components. |
+
+Context objects are sanitized before writing: sensitive keys (`password`, `token`, `authorization`, `cookie`, and more, extendable via `redactKeys`) become `[REDACTED]`, circular references become `[Circular]`, depth is capped by `maxDepth` (default 8), and `Error`/`Date` values are serialized. Transport write and flush failures are reported through `onTransportError` and never make logging throw.
+
+## Types
+
+`Logger`, `LogLevel`, `LogEntry`, `LogContext`, `LogObject`, `LogValue`, `LogTransport`, `ConsoleLike`, `MemoryLogTransport`, `LoggerOptions`, `LoggerPluginOptions`, `LoggerErrorCode`

package/package.json

@@ -0,0 +1,25 @@
+{
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "name": "@vobs/logger",
+  "version": "1.0.0",
+  "description": "Structured, transport-based logging for Vobs applications.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@vobs/reactivity": "1.0.0",
+    "@vobs/vobs": "1.0.0"
+  },
+  "scripts": {
+    "test": "vitest --environment jsdom"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createText, createVobs } from '@vobs/vobs'
+import {
+  LOGGER_KEY,
+  LoggerError,
+  createConsoleTransport,
+  createLogger,
+  createMemoryTransport,
+  loggerPlugin,
+  useLogger
+} from './index'
+
+describe('@vobs/logger', () => {
+  it('按级别过滤，并合并子日志的结构化上下文', () => {
+    const memory = createMemoryTransport()
+    const logger = createLogger({
+      level: 'info',
+      context: { app: 'console', release: 3 },
+      transports: [memory],
+      clock: () => new Date('2026-09-03T00:00:00.000Z')
+    })
+
+    logger.debug('ignored')
+    logger.child({ requestId: 'request-1' }).warn('request failed', { status: 503 })
+
+    expect(memory.entries).toEqual([{
+      timestamp: '2026-09-03T00:00:00.000Z',
+      level: 'warn',
+      message: 'request failed',
+      context: { app: 'console', release: 3, requestId: 'request-1', status: 503 }
+    }])
+    expect(Object.isFrozen(memory.entries[0])).toBe(true)
+    expect(Object.isFrozen(memory.entries[0].context)).toBe(true)
+    logger.dispose()
+  })
+
+  it('默认脱敏敏感键，安全处理错误、深层对象和循环值', () => {
+    const memory = createMemoryTransport()
+    const circular: { self?: unknown } = {}
+    circular.self = circular
+    const logger = createLogger({ transports: [memory], maxDepth: 2 })
+
+    logger.error('login failed', {
+      token: 'private',
+      nested: { authorization: 'secret', value: true },
+      error: new Error('denied'),
+      circular,
+      deep: { one: { two: { three: true } } }
+    })
+
+    expect(memory.entries[0].context).toMatchObject({
+      token: '[REDACTED]',
+      nested: { authorization: '[REDACTED]', value: true },
+      error: { name: 'Error', message: 'denied' },
+      circular: { self: '[Circular]' },
+      deep: { one: { two: '[MaxDepth]' } }
+    })
+    logger.dispose()
+  })
+
+  it('flush 等待异步 transport，并隔离 transport 写入和 flush 错误', async () => {
+    let resolveWrite: (() => void) | undefined
+    const onTransportError = vi.fn()
+    const asyncTransport = {
+      write: vi.fn(() => new Promise<void>(resolve => { resolveWrite = resolve })),
+      flush: vi.fn()
+    }
+    const brokenTransport = {
+      write: () => { throw new Error('write failed') },
+      flush: () => { throw new Error('flush failed') }
+    }
+    const logger = createLogger({ transports: [asyncTransport, brokenTransport], onTransportError })
+    logger.info('queued')
+    const flushed = logger.flush()
+    expect(asyncTransport.flush).not.toHaveBeenCalled()
+    resolveWrite?.()
+    await flushed
+
+    expect(asyncTransport.flush).toHaveBeenCalledTimes(1)
+    expect(onTransportError).toHaveBeenCalledWith(expect.any(Error), brokenTransport, expect.objectContaining({ message: 'queued' }))
+    expect(onTransportError).toHaveBeenCalledWith(expect.any(Error), brokenTransport, undefined)
+    logger.dispose()
+  })
+
+  it('console transport 使用对应级别输出，内存 transport 可以限制和清空', () => {
+    const output = vi.fn()
+    const consoleTransport = createConsoleTransport({ warn: output })
+    const memory = createMemoryTransport(2)
+    const logger = createLogger({ level: 'debug', transports: [consoleTransport, memory] })
+    logger.warn('notice', { count: 1 })
+    logger.info('first')
+    logger.info('second')
+
+    expect(output).toHaveBeenCalledWith('[warn] notice', { count: 1 })
+    expect(memory.entries.map(entry => entry.message)).toEqual(['first', 'second'])
+    memory.clear()
+    expect(memory.entries).toEqual([])
+    logger.dispose()
+  })
+
+  it('子 Logger 销毁只停止自己的写入，不关闭父 Logger 的共享 transport', () => {
+    const memory = createMemoryTransport()
+    const logger = createLogger({ transports: [memory] })
+    const child = logger.child({ requestId: 'request-1' })
+
+    child.dispose()
+    child.info('ignored')
+    logger.info('parent remains active')
+
+    expect(memory.entries.map(entry => entry.message)).toEqual(['parent remains active'])
+    logger.dispose()
+  })
+
+  it('loggerPlugin 注入上下文并在应用销毁后停止写入自有 logger', () => {
+    const memory = createMemoryTransport()
+    let injected: ReturnType<typeof createLogger> | undefined
+    const app = createVobs({
+      render: () => createText('logger'),
+      plugins: [
+        loggerPlugin({ transports: [memory] }),
+        { name: 'consumer', install(context) { injected = context.inject(LOGGER_KEY) } }
+      ]
+    })
+
+    injected?.info('before destroy')
+    app.destroy()
+    injected?.info('after destroy')
+    expect(memory.entries.map(entry => entry.message)).toEqual(['before destroy'])
+  })
+
+  it('未安装插件时 useLogger 给出明确错误', () => {
+    const app = createVobs({ render: () => {
+      useLogger()
+      return createText('')
+    } })
+    expect(() => app.mount(document.createElement('div'))).toThrowError(
+      expect.objectContaining({ code: 'LOGGER_CONTEXT_MISSING' })
+    )
+    expect(LoggerError).toBeDefined()
+  })
+})

package/src/index.ts

@@ -0,0 +1,324 @@
+import { getCurrentOwner, onDispose } from '@vobs/reactivity'
+import { createInjectionKey, inject, type InjectionKey, type VobsPlugin } from '@vobs/vobs'
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+export type LogValue = string | number | boolean | null | Readonly<LogObject> | readonly LogValue[]
+
+export interface LogObject {
+  readonly [key: string]: LogValue
+}
+
+export type LogContext = Readonly<Record<string, unknown>>
+
+export interface LogEntry {
+  readonly timestamp: string
+  readonly level: LogLevel
+  readonly message: string
+  readonly context: Readonly<LogObject>
+}
+
+export interface LogTransport {
+  write(entry: LogEntry): void | PromiseLike<void>
+  flush?(): void | PromiseLike<void>
+  dispose?(): void
+}
+
+export interface Logger {
+  readonly level: LogLevel
+  log(level: LogLevel, message: string, context?: LogContext): void
+  debug(message: string, context?: LogContext): void
+  info(message: string, context?: LogContext): void
+  warn(message: string, context?: LogContext): void
+  error(message: string, context?: LogContext): void
+  child(context: LogContext): Logger
+  flush(): Promise<void>
+  dispose(): void
+}
+
+export interface LoggerOptions {
+  readonly level?: LogLevel
+  readonly context?: LogContext
+  readonly transports?: readonly LogTransport[]
+  readonly redactKeys?: readonly string[]
+  readonly maxDepth?: number
+  readonly clock?: () => Date
+  readonly onTransportError?: (error: unknown, transport: LogTransport, entry?: LogEntry) => void
+}
+
+export interface LoggerPluginOptions extends LoggerOptions {
+  readonly logger?: Logger
+}
+
+export interface ConsoleLike {
+  debug?: (...data: unknown[]) => void
+  info?: (...data: unknown[]) => void
+  warn?: (...data: unknown[]) => void
+  error?: (...data: unknown[]) => void
+  log?: (...data: unknown[]) => void
+}
+
+export interface MemoryLogTransport extends LogTransport {
+  readonly entries: readonly LogEntry[]
+  clear(): void
+}
+
+export type LoggerErrorCode = 'LOGGER_CONTEXT_MISSING' | 'INVALID_LEVEL' | 'INVALID_TRANSPORT' | 'INVALID_MAX_DEPTH'
+
+export class LoggerError extends Error {
+  readonly code: LoggerErrorCode
+
+  constructor(code: LoggerErrorCode, message: string) {
+    super(message)
+    this.name = 'LoggerError'
+    this.code = code
+  }
+}
+
+export const LOGGER_KEY: InjectionKey<Logger> = createInjectionKey<Logger>('vobs.logger')
+
+const levels: Readonly<Record<LogLevel, number>> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+}
+
+const defaultRedactKeys = ['password', 'passwd', 'secret', 'token', 'authorization', 'cookie']
+
+interface LoggerState {
+  readonly level: LogLevel
+  readonly transports: readonly LogTransport[]
+  readonly redactKeys: ReadonlySet<string>
+  readonly maxDepth: number
+  readonly clock: () => Date
+  readonly onTransportError: LoggerOptions['onTransportError']
+  readonly pending: Set<Promise<void>>
+  disposed: boolean
+}
+
+export function createLogger(options: LoggerOptions = {}): Logger {
+  const level = options.level ?? 'info'
+  if (!isLogLevel(level)) throw new LoggerError('INVALID_LEVEL', `Vobs Logger: 不支持日志级别 ${String(level)}`)
+
+  const maxDepth = options.maxDepth ?? 8
+  if (!Number.isInteger(maxDepth) || maxDepth < 0) {
+    throw new LoggerError('INVALID_MAX_DEPTH', 'Vobs Logger: maxDepth 必须是大于等于 0 的整数')
+  }
+
+  const transports = options.transports ?? [createConsoleTransport()]
+  if (transports.some(transport => !transport || typeof transport.write !== 'function')) {
+    throw new LoggerError('INVALID_TRANSPORT', 'Vobs Logger: transport 必须提供 write(entry)')
+  }
+
+  const state: LoggerState = {
+    level,
+    transports,
+    redactKeys: new Set((options.redactKeys ?? defaultRedactKeys).map(key => key.toLowerCase())),
+    maxDepth,
+    clock: options.clock ?? (() => new Date()),
+    onTransportError: options.onTransportError,
+    pending: new Set(),
+    disposed: false
+  }
+  const logger = createLoggerScope(state, options.context ?? {}, true)
+  if (getCurrentOwner()) onDispose(logger.dispose)
+  return logger
+}
+
+export function createConsoleTransport(target: ConsoleLike | undefined = globalThis.console): LogTransport {
+  return {
+    write(entry): void {
+      const output = target?.[entry.level] ?? target?.log
+      output?.call(target, `[${entry.level}] ${entry.message}`, entry.context)
+    }
+  }
+}
+
+export function createMemoryTransport(limit = Infinity): MemoryLogTransport {
+  if ((!Number.isInteger(limit) && limit !== Infinity) || limit <= 0) {
+    throw new RangeError('Vobs Logger: memory transport 的 limit 必须是正整数或 Infinity')
+  }
+
+  const entries: LogEntry[] = []
+  return {
+    get entries(): readonly LogEntry[] {
+      return entries
+    },
+    write(entry): void {
+      entries.push(entry)
+      if (entries.length > limit) entries.splice(0, entries.length - limit)
+    },
+    clear(): void {
+      entries.length = 0
+    }
+  }
+}
+
+export function loggerPlugin(options: LoggerPluginOptions = {}): VobsPlugin {
+  return {
+    name: '@vobs/logger',
+    version: '0.1.0',
+    install(context) {
+      const ownedLogger = options.logger ? undefined : createLogger(options)
+      context.provide(LOGGER_KEY, options.logger ?? ownedLogger!)
+      return () => ownedLogger?.dispose()
+    }
+  }
+}
+
+export function useLogger(): Logger {
+  const logger = inject(LOGGER_KEY)
+  if (!logger) throw new LoggerError('LOGGER_CONTEXT_MISSING', 'Vobs Logger: 找不到上下文，请安装 loggerPlugin')
+  return logger
+}
+
+function createLoggerScope(state: LoggerState, baseContext: LogContext, ownsTransports = false): Logger {
+  const context = { ...baseContext }
+  let disposed = false
+  return {
+    level: state.level,
+
+    log(level, message, details = {}): void {
+      if (state.disposed || disposed || !isLogLevel(level) || levels[level] < levels[state.level]) return
+      const entry = freezeEntry({
+        timestamp: state.clock().toISOString(),
+        level,
+        message,
+        context: sanitizeContext({ ...context, ...details }, state.redactKeys, state.maxDepth)
+      })
+      for (const transport of state.transports) writeToTransport(state, transport, entry)
+    },
+
+    debug(message, details): void {
+      this.log('debug', message, details)
+    },
+
+    info(message, details): void {
+      this.log('info', message, details)
+    },
+
+    warn(message, details): void {
+      this.log('warn', message, details)
+    },
+
+    error(message, details): void {
+      this.log('error', message, details)
+    },
+
+    child(details): Logger {
+      return createLoggerScope(state, { ...context, ...details })
+    },
+
+    async flush(): Promise<void> {
+      while (state.pending.size > 0) await Promise.all([...state.pending])
+      for (const transport of state.transports) {
+        try {
+          await transport.flush?.()
+        } catch (error) {
+          reportTransportError(state, error, transport)
+        }
+      }
+    },
+
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      if (!ownsTransports || state.disposed) return
+      state.disposed = true
+      for (const transport of state.transports) {
+        try {
+          transport.dispose?.()
+        } catch (error) {
+          reportTransportError(state, error, transport)
+        }
+      }
+    }
+  }
+}
+
+function writeToTransport(state: LoggerState, transport: LogTransport, entry: LogEntry): void {
+  try {
+    const result = transport.write(entry)
+    if (!isPromiseLike(result)) return
+    const pending = Promise.resolve(result).catch(error => {
+      reportTransportError(state, error, transport, entry)
+    })
+    state.pending.add(pending)
+    void pending.then(() => state.pending.delete(pending))
+  } catch (error) {
+    reportTransportError(state, error, transport, entry)
+  }
+}
+
+function reportTransportError(
+  state: LoggerState,
+  error: unknown,
+  transport: LogTransport,
+  entry?: LogEntry
+): void {
+  try {
+    state.onTransportError?.(error, transport, entry)
+  } catch {
+    // Transport error reporting must never make application logging throw.
+  }
+}
+
+function sanitizeContext(input: LogContext, redactKeys: ReadonlySet<string>, maxDepth: number): LogObject {
+  const seen = new WeakSet<object>()
+  return Object.freeze(sanitizeObject(input, redactKeys, maxDepth, seen))
+}
+
+function sanitizeObject(
+  input: LogContext,
+  redactKeys: ReadonlySet<string>,
+  depth: number,
+  seen: WeakSet<object>
+): LogObject {
+  const output: Record<string, LogValue> = {}
+  for (const [key, value] of Object.entries(input)) {
+    output[key] = redactKeys.has(key.toLowerCase())
+      ? '[REDACTED]'
+      : sanitizeValue(value, redactKeys, depth, seen)
+  }
+  return Object.freeze(output)
+}
+
+function sanitizeValue(
+  value: unknown,
+  redactKeys: ReadonlySet<string>,
+  depth: number,
+  seen: WeakSet<object>
+): LogValue {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+  if (typeof value === 'number') return Number.isFinite(value) ? value : String(value)
+  if (typeof value === 'bigint' || typeof value === 'symbol' || typeof value === 'undefined') return String(value)
+  if (typeof value === 'function') return `[Function ${value.name || 'anonymous'}]`
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString()
+  if (value instanceof Error) {
+    return Object.freeze({
+      name: value.name,
+      message: value.message,
+      ...(value.stack ? { stack: value.stack } : {})
+    })
+  }
+  if (depth === 0) return '[MaxDepth]'
+  if (seen.has(value as object)) return '[Circular]'
+  seen.add(value as object)
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map(item => sanitizeValue(item, redactKeys, depth - 1, seen)))
+  }
+  return sanitizeObject(value as LogContext, redactKeys, depth - 1, seen)
+}
+
+function freezeEntry(entry: LogEntry): LogEntry {
+  return Object.freeze(entry)
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<void> {
+  return Boolean(value) && typeof (value as PromiseLike<void>).then === 'function'
+}
+
+function isLogLevel(value: unknown): value is LogLevel {
+  return typeof value === 'string' && value in levels
+}