@pori15/logixlysia 6.0.8 → 6.0.9

package/README.md

@@ -1,49 +1,79 @@
-<div align="center">
-  <h1><code>🦊</code> Logixlysia</h1>
-  <strong>Logixlysia is a logging library for ElysiaJS</strong>
-  <img src="https://github.com/PunGrumpy/logixlysia/blob/main/apps/docs/app/opengraph-image.png?raw=true" alt="Logixlysia" width="100%" height="auto" />
-</div>
-
-## `📩` Installation
-
-```bash
-bun add logixlysia
-```
-
-## `📝` Usage
-
-```ts
-import { Elysia } from 'elysia'
-import logixlysia from 'logixlysia' // or import { logixlysia } from 'logixlysia'
-
-const app = new Elysia({
-    name: "Elysia with Logixlysia"
-})
-  .use(
-    logixlysia({
-      config: {
-        showStartupMessage: true,
-        startupMessageFormat: 'simple',
-        timestamp: {
-          translateTime: 'yyyy-mm-dd HH:MM:ss.SSS'
-        },
-        logFilePath: './logs/example.log',
-        ip: true,
-        customLogFormat:
-          '🦊 {now} {level} {duration} {method} {pathname} {status} {message} {ip}'
-        }
-    }))
-    .get('/', () => {
-        return { message: 'Welcome to Basic Elysia with Logixlysia' }
-    })
-        
-app.listen(3000)
-```
-
-## `📚` Documentation
-
-Check out the [website](https://logixlysia.vercel.app) for more detailed documentation and examples.
-
-## `📄` License
-
-Licensed under the [MIT License](LICENSE).
+<div align="center">
+  <h1><code>🦊</code> Logixlysia</h1>
+  <strong>Logixlysia is a logging library for ElysiaJS</strong>
+  <img src="https://github.com/PunGrumpy/logixlysia/blob/main/apps/docs/app/opengraph-image.png?raw=true" alt="Logixlysia" width="100%" height="auto" />
+</div>
+
+## `📩` Installation
+
+```bash
+bun add logixlysia
+```
+
+## `📝` Usage
+
+### Basic
+
+```ts
+import { Elysia } from 'elysia'
+import logixlysia from 'logixlysia'
+
+const app = new Elysia()
+  .use(logixlysia())
+  .get('/', () => 'Hello World')
+  .listen(3000)
+```
+
+### With Configuration
+
+```ts
+app.use(logixlysia({
+  startup: {
+    show: true,
+    format: 'simple',
+  },
+  format: {
+    timestamp: 'yyyy-mm-dd HH:MM:ss.SSS',
+    showIp: true,
+    template: '🦊 {now} {level} {duration} {method} {pathname} {status} {message} {ip}',
+  },
+  file: {
+    path: './logs/example.log',
+    rotation: {
+      maxSize: '10m',
+      maxFiles: 7,
+      compress: true,
+    },
+  },
+  logLevel: ['ERROR', 'WARNING'],
+}))
+```
+
+## `⚙️` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `startup.show` | `boolean` | `true` | Show startup message |
+| `startup.format` | `"simple" \| "banner"` | `"banner"` | Startup message style |
+| `format.colors` | `boolean` | `true` (TTY) | Enable colored output |
+| `format.timestamp` | `string` | — | Timestamp format pattern (e.g. `'yyyy-mm-dd HH:MM:ss.SSS'`) |
+| `format.template` | `string` | — | Custom log format template |
+| `format.showIp` | `boolean` | `false` | Show IP address in logs |
+| `logLevel` | `LogLevel \| LogLevel[]` | — | Filter logs by level(s) |
+| `file` | `false \| { path, rotation? }` | — | File logging config (`false` to disable) |
+| `file.path` | `string` | — | Log file path (required when file logging enabled) |
+| `file.rotation` | `LogRotationConfig` | — | Log file rotation settings |
+| `transports` | `Transport[] \| { targets, only? }` | — | Custom transports |
+| `pino` | `PinoLoggerOptions` | — | Pino logger options |
+| `error.typeBaseUrl` | `string` | — | Base URL for error types (RFC 9457) |
+| `error.errorMap` | `Record<string, ErrorMapping>` | — | Error code to HTTP status mapping |
+| `error.resolve` | `ErrorResolver` | — | Custom error resolver function |
+| `error.verbose` | `boolean` | `false` | Show full error details in console |
+
+## `📚` Documentation
+
+Check out the [website](https://logixlysia.vercel.app) for more detailed documentation and examples.
+
+## `📄` License
+
+Licensed under the [MIT License](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pori15/logixlysia",
-  "version": "6.0.8",
+  "version": "6.0.9",
   "description": "🦊 Logixlysia is a logger for Elysia",
   "type": "module",
   "main": "dist/index.js",

package/src/extensions/index.ts

@@ -5,7 +5,7 @@ export const startServer = (
   server: { port?: number; hostname?: string; protocol?: string | null },
   options: Options
 ): void => {
-  const showStartupMessage = options.config?.showStartupMessage ?? true;
+  const showStartupMessage = options.startup?.show ?? true;
   if (!showStartupMessage) {
     return;
   }
@@ -18,7 +18,7 @@ export const startServer = (
   const url = `${protocol}://${hostname}:${port}`;
   const message = `🦊 Elysia is running at ${url}`;
 
-  const format = options.config?.startupMessageFormat ?? "banner";
+  const format = options.startup?.format ?? "banner";
   if (format === "simple") {
     console.log(message);
     return;

package/src/index.ts

@@ -52,7 +52,7 @@ export const logixlysia = (options: Options = {}): Logixlysia => {
     name: "Logixlysia",
   });
 
-  const errorConfig = options.config?.error;
+  const errorConfig = options.error;
 
   return (
     app
@@ -131,16 +131,21 @@ export { normalizeToProblem } from "./utils/handle-error";
 // ==========================================
 
 export type {
+  ErrorConfig,
   ErrorMapping,
   ErrorResolver,
+  FileConfig,
+  FormatConfig,
   Logger,
   LogixlysiaContext,
   LogixlysiaStore,
   LogLevel,
   Options,
   Pino,
+  StartupConfig,
   StoreData,
   Transport,
+  TransportsConfig,
 } from "./interfaces";
 
 export default logixlysia;

package/src/interfaces.ts

@@ -5,15 +5,21 @@ import type {
 import type { ProblemError } from "./error/errors";
 import type { Code } from "./error/type";
 
+/** Pino Logger 实例类型 */
 export type Pino = PinoLogger<never, boolean>;
 
+/** 日志级别 */
 export type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
 
+/** 单次请求携带的计时和路径数据 */
 export interface StoreData {
+  /** 请求开始的纳秒时间戳（hrtime） */
   beforeTime: bigint;
+  /** 缓存的 URL pathname，避免重复解析 */
   pathname: string;
 }
 
+/** Elysia store 中挂载的 logixlysia 状态 */
 export interface LogixlysiaStore {
   beforeTime?: bigint;
   logger: Logger;
@@ -22,7 +28,15 @@ export interface LogixlysiaStore {
   [key: string]: unknown;
 }
 
+/** 自定义日志传输接口（如 Elasticsearch、Slack 等） */
 export interface Transport {
+  /**
+   * 接收一条日志并输出到外部系统
+   *
+   * @param level - 日志级别
+   * @param message - 日志消息
+   * @param meta - 附加元数据（请求信息、耗时等）
+   */
   log: (
     level: LogLevel,
     message: string,
@@ -30,41 +44,39 @@ export interface Transport {
   ) => void | Promise<void>;
 }
 
+/** 日志文件轮转配置 */
 export interface LogRotationConfig {
+  /** 轮转后是否压缩旧文件 */
   compress?: boolean;
+  /** 压缩算法 */
   compression?: "gzip";
-  /**
-   * Rotate at a fixed interval, e.g. '1d', '12h'.
-   */
+  /** 固定间隔轮转，如 `'1d'`、`'12h'` */
   interval?: string;
-  /**
-   * Keep at most N files or keep files for a duration like '7d'.
-   */
+  /** 保留的最大文件数量或时长，如 `10` 或 `'7d'` */
   maxFiles?: number | string;
-  /**
-   * Max log file size before rotation, e.g. '10m', '5k', or a byte count.
-   */
+  /** 单个日志文件最大体积，如 `'10m'`、`'5k'`，或字节数 */
   maxSize?: string | number;
 }
 
-export interface LogFilter {
-  /**
-   * Array of log levels to allow. If specified, only logs with these levels will be processed.
-   * If not specified, all log levels will be allowed.
-   */
-  level?: LogLevel[];
-}
-
 // ==========================================
 // Error Mapping
 // ==========================================
 
+/** 错误码到 HTTP 响应的映射条目 */
 export interface ErrorMapping {
+  /** 错误详情描述 */
   detail?: string;
+  /** HTTP 状态码 */
   status: number;
+  /** 错误标题 */
   title: string;
 }
 
+/**
+ * 自定义错误解析回调
+ *
+ * 返回 `ProblemError` 表示已处理，返回 `void` 交给下一层处理
+ */
 export type ErrorResolver = (
   error: unknown,
   context: { code: Code; path: string; request: Request }
@@ -74,112 +86,113 @@ export type ErrorResolver = (
 // Options
 // ==========================================
 
+/** 启动消息配置 */
+export interface StartupConfig {
+  /** 启动消息格式，默认 `"banner"` */
+  format?: "simple" | "banner";
+  /** 是否显示启动消息，默认 `true` */
+  show?: boolean;
+}
+
+/** 日志格式配置 */
+export interface FormatConfig {
+  /** 是否启用彩色输出，默认 `true`（仅 TTY） */
+  colors?: boolean;
+  /** 是否在日志中显示请求 IP，默认 `false` */
+  showIp?: boolean;
+  /** 自定义日志模板，如 `'🦊 {now} {level} {method} {pathname} {status}'` */
+  template?: string;
+  /** 时间戳格式，如 `'yyyy-mm-dd HH:MM:ss.SSS'` */
+  timestamp?: string;
+}
+
+/** 文件日志配置 */
+export interface FileConfig {
+  /** 日志文件路径（必填） */
+  path: string;
+  /** 日志轮转配置 */
+  rotation?: LogRotationConfig;
+}
+
+/** 自定义传输配置 */
+export interface TransportsConfig {
+  /** 设为 `true` 时只使用 transports，禁用控制台和文件输出 */
+  only?: boolean;
+  /** 传输目标列表 */
+  targets: Transport[];
+}
+
+/** 错误处理配置 */
+export interface ErrorConfig {
+  /** 错误码映射表（Postgres / MySQL / 自定义错误码） */
+  errorMap?: Record<string, ErrorMapping>;
+  /** 自定义错误解析回调 */
+  resolve?: ErrorResolver;
+  /** 自定义错误类型的 Base URL（RFC 9457） */
+  typeBaseUrl?: string;
+  /** 是否在控制台显示完整错误详情（detail、extensions），默认 `false` */
+  verbose?: boolean;
+}
+
+/** Logixlysia 插件配置 */
 export interface Options {
-  config?: {
-    showStartupMessage?: boolean;
-    startupMessageFormat?: "simple" | "banner";
-    useColors?: boolean;
-    ip?: boolean;
-    timestamp?: {
-      translateTime?: string;
-    };
-    customLogFormat?: string;
-
-    // Filtering
-    logFilter?: LogFilter;
-
-    // Outputs
-    transports?: Transport[];
-    useTransportsOnly?: boolean;
-    disableInternalLogger?: boolean;
-    disableFileLogging?: boolean;
-    logFilePath?: string;
-    logRotation?: LogRotationConfig;
-
-    // Pino
-    pino?: (PinoLoggerOptions & { prettyPrint?: boolean }) | undefined;
-
-    // Error handling
-    error?: {
-      /**
-       * 自定义错误类型的 Base URL
-       * @example "https://api.mysite.com/errors"
-       */
-      typeBaseUrl?: string;
-
-      /**
-       * 错误码映射表（Postgres / MySQL / 自定义错误码）
-       * 键为错误码字符串，值为 ProblemError 字段
-       *
-       * @example
-       * ```ts
-       * errorMap: {
-       *   '23505': { status: 409, title: 'Resource already exists', detail: 'Unique constraint violation' },
-       *   '23503': { status: 400, title: 'Foreign key constraint failed' },
-       *   'ER_DUP_ENTRY': { status: 409, title: 'Duplicate entry' },
-       * }
-       * ```
-       */
-      errorMap?: Record<string, ErrorMapping>;
-
-      /**
-       * 用户自定义错误解析回调
-       * 返回 ProblemError 表示已处理，返回 void 表示交给下一层
-       *
-       * @example
-       * ```ts
-       * resolve(error, { code, path }) {
-       *   if (isStripeError(error)) {
-       *     return createProblem(402, { detail: error.message })
-       *   }
-       *   // return void → 交给下一层
-       * }
-       * ```
-       */
-      resolve?: ErrorResolver;
-
-      /**
-       * 是否在控制台显示完整的错误详情（包括 detail 和 extensions）
-       * @default false
-       */
-      verboseErrorLogging?: boolean;
-    };
-  };
+  /** 错误处理配置 */
+  error?: ErrorConfig;
+  /** 文件日志配置，设为 `false` 禁用文件日志 */
+  file?: false | FileConfig;
+  /** 日志格式配置 */
+  format?: FormatConfig;
+  /** 日志级别过滤，接受单个级别或级别数组 */
+  logLevel?: LogLevel | LogLevel[];
+  /** Pino Logger 原生配置透传 */
+  pino?: PinoLoggerOptions;
+  /** 启动消息配置 */
+  startup?: StartupConfig;
+  /** 自定义传输（数组或带 `only` 选项的对象） */
+  transports?: Transport[] | TransportsConfig;
 }
 
 // ==========================================
 // Logger
 // ==========================================
 
+/** Logger 实例，可通过 `store.logger` 访问 */
 export interface Logger {
+  /** 记录 DEBUG 级别日志 */
   debug: (
     request: Request,
     message: string,
     context?: Record<string, unknown>
   ) => void;
+  /** 记录 ERROR 级别日志 */
   error: (
     request: Request,
     message: string,
     context?: Record<string, unknown>
   ) => void;
+  /** 处理 HTTP 错误并输出日志 */
   handleHttpError: (
     request: Request,
     error: ProblemError,
     store: StoreData,
     options: Options
   ) => void;
+  /** 记录 INFO 级别日志 */
   info: (
     request: Request,
     message: string,
     context?: Record<string, unknown>
   ) => void;
+  /** 记录指定级别的日志 */
   log: (
     level: LogLevel,
     request: Request,
     data: Record<string, unknown>,
     store: StoreData
   ) => void;
+  /** 底层 Pino Logger 实例 */
   pino: Pino;
+  /** 记录 WARNING 级别日志 */
   warn: (
     request: Request,
     message: string,
@@ -187,6 +200,7 @@ export interface Logger {
   ) => void;
 }
 
+/** Logixlysia 请求上下文 */
 export interface LogixlysiaContext {
   request: Request;
   store: LogixlysiaStore;

package/src/logger/create-logger.ts

@@ -4,8 +4,7 @@ import type { LogLevel, Options, Pino, StoreData } from "../interfaces";
 import { pad2, pad3 } from "../utils/format";
 
 const shouldUseColors = (options: Options): boolean => {
-  const config = options.config;
-  const enabledByConfig = config?.useColors ?? true;
+  const enabledByConfig = options.format?.colors ?? true;
 
   // Avoid ANSI sequences in non-interactive output (pipes, CI logs, files).
   const isTty =
@@ -169,15 +168,15 @@ export const formatLine = ({
   store: StoreData;
   options: Options;
 }): string => {
-  const config = options.config;
+  const fmt = options.format;
   const useColors = shouldUseColors(options);
   const format =
-    config?.customLogFormat ??
+    fmt?.template ??
     "🦊 {now} {level} {duration} {method} {pathname} {status} {message} {ip} {context}";
 
   const now = new Date();
   const epoch = String(now.getTime());
-  const rawTimestamp = formatTimestamp(now, config?.timestamp?.translateTime);
+  const rawTimestamp = formatTimestamp(now, fmt?.timestamp);
   const timestamp = getColoredTimestamp(rawTimestamp, useColors);
 
   const message = typeof data.message === "string" ? data.message : "";
@@ -193,7 +192,7 @@ export const formatLine = ({
       ? 200
       : getStatusCode(statusValue);
   const status = String(statusCode);
-  const ip = config?.ip === true ? getIp(request) : "";
+  const ip = fmt?.showIp === true ? getIp(request) : "";
   const ctxString = getContextString(data.context);
   const coloredLevel = getColoredLevel(level, useColors);
   const coloredMethod = getColoredMethod(request.method, useColors);

package/src/logger/handle-http-error.ts

@@ -1,8 +1,22 @@
 import type { ProblemError } from "../error/errors";
-import type { LogLevel, Options, StoreData } from "../interfaces";
+import type {
+  LogLevel,
+  Options,
+  StoreData,
+  Transport,
+  TransportsConfig,
+} from "../interfaces";
 import { logToTransports } from "../output";
 import { logToFile } from "../output/file";
 
+const normalizeTransports = (
+  transports?: Transport[] | TransportsConfig
+): { targets: Transport[]; only: boolean } => {
+  if (!transports) return { targets: [], only: false };
+  if (Array.isArray(transports)) return { targets: transports, only: false };
+  return { targets: transports.targets, only: transports.only === true };
+};
+
 /**
  * 统一输出管道：transports → file → console
  * handleHttpError 和 log 共用同一管道，不再重复判断配置
@@ -15,27 +29,31 @@ const outputPipeline = (
   options: Options,
   consoleMessage?: string
 ): void => {
-  const config = options.config;
+  const { targets, only: transportsOnly } = normalizeTransports(
+    options.transports
+  );
 
   // 1. Transports
-  logToTransports({ level, request, data, store, options });
+  logToTransports({ level, request, data, store, transports: targets });
 
   // 2. File
-  const useTransportsOnly = config?.useTransportsOnly === true;
-  const disableFileLogging = config?.disableFileLogging === true;
-  if (!(useTransportsOnly || disableFileLogging)) {
-    const filePath = config?.logFilePath;
-    if (filePath) {
-      logToFile({ filePath, level, request, data, store, options }).catch(
-        (e) => {
-          console.error(e);
-        }
-      );
-    }
+  const fileConfig = options.file;
+  const hasFile = fileConfig !== false && fileConfig !== undefined;
+  if (!transportsOnly && hasFile) {
+    logToFile({
+      filePath: fileConfig.path,
+      level,
+      request,
+      data,
+      store,
+      options,
+    }).catch((e) => {
+      console.error(e);
+    });
   }
 
   // 3. Console
-  if (useTransportsOnly || config?.disableInternalLogger === true) return;
+  if (transportsOnly) return;
 
   if (consoleMessage) {
     switch (level) {
@@ -63,7 +81,6 @@ export const handleHttpError = (
   store: StoreData,
   options: Options
 ): void => {
-  const config = options.config;
   const level: LogLevel = problem.status >= 500 ? "ERROR" : "WARNING";
   const rfcData = problem.toJSON();
   const data = {
@@ -73,17 +90,18 @@ export const handleHttpError = (
   };
 
   // 构建 console 消息
+  const { only: transportsOnly } = normalizeTransports(options.transports);
   let consoleMessage = "";
-  if (!(config?.useTransportsOnly || config?.disableInternalLogger)) {
+  if (!transportsOnly) {
     let timestamp = "";
-    if (config?.timestamp) {
+    if (options.format?.timestamp) {
       timestamp = `[${new Date().toISOString()}] `;
     }
     const pathname = store.pathname || new URL(request.url).pathname;
     consoleMessage = `${timestamp}${level} ${request.method} ${pathname} ${problem.status} - ${problem.title}`;
 
     // 详细错误日志
-    if (config?.error?.verboseErrorLogging) {
+    if (options.error?.verbose) {
       const parts = [consoleMessage];
       if (rfcData.detail) parts.push(`  Detail: ${rfcData.detail}`);
       if (rfcData.instance) parts.push(`  Instance: ${rfcData.instance}`);

package/src/logger/index.ts

@@ -1,25 +1,23 @@
 import pino from "pino";
-import type {
-  LogFilter,
-  Logger,
-  LogLevel,
-  Options,
-  Pino,
-  StoreData,
-} from "../interfaces";
+import type { Logger, LogLevel, Options, Pino, StoreData } from "../interfaces";
 import { formatLine } from "./create-logger";
 import { handleHttpError, outputPipeline } from "./handle-http-error";
 
-export const createLogger = (options: Options = {}): Logger => {
-  const config = options.config;
-
-  const pinoConfig = config?.pino;
-  const { prettyPrint, ...pinoOptions } = pinoConfig ?? {};
+const shouldLog = (
+  level: LogLevel,
+  logLevel?: LogLevel | LogLevel[]
+): boolean => {
+  if (logLevel === undefined) return true;
+  const levels = Array.isArray(logLevel) ? logLevel : [logLevel];
+  if (levels.length === 0) return true;
+  return levels.includes(level);
+};
 
-  const shouldPrettyPrint =
-    prettyPrint === true && pinoOptions.transport === undefined;
+export const createLogger = (options: Options = {}): Logger => {
+  const pinoOptions = options.pino ?? {};
+  const isPrettyPrint = pinoOptions.transport === undefined;
 
-  const pinoLogger: Pino = shouldPrettyPrint
+  const pinoLogger: Pino = isPrettyPrint
     ? pino({
         ...pinoOptions,
         level: pinoOptions.level ?? "info",
@@ -29,7 +27,7 @@ export const createLogger = (options: Options = {}): Logger => {
           target: "pino-pretty",
           options: {
             colorize: process.stdout?.isTTY === true,
-            translateTime: config?.timestamp?.translateTime,
+            translateTime: options.format?.timestamp,
             messageKey: pinoOptions.messageKey,
             errorKey: pinoOptions.errorKey,
           },
@@ -42,20 +40,13 @@ export const createLogger = (options: Options = {}): Logger => {
         errorKey: pinoOptions.errorKey,
       });
 
-  const shouldLog = (level: LogLevel, logFilter?: LogFilter): boolean => {
-    if (!logFilter?.level || logFilter.level.length === 0) {
-      return true;
-    }
-    return logFilter.level.includes(level);
-  };
-
   const log = (
     level: LogLevel,
     request: Request,
     data: Record<string, unknown>,
     store: StoreData
   ): void => {
-    if (!shouldLog(level, config?.logFilter)) {
+    if (!shouldLog(level, options.logLevel)) {
       return;
     }
 

package/src/output/file.ts

@@ -27,7 +27,8 @@ export const logToFile = async (input: LogToFileInput): Promise<void> => {
   await ensureDir(dirname(filePath));
   await appendFile(filePath, line, { encoding: "utf-8" });
 
-  const rotation = options.config?.logRotation;
+  const rotation =
+    options.file && options.file !== false ? options.file.rotation : undefined;
   if (!rotation) {
     return;
   }

package/src/output/index.ts

@@ -1,16 +1,15 @@
-import type { LogLevel, Options, StoreData } from "../interfaces";
+import type { LogLevel, StoreData, Transport } from "../interfaces";
 
 interface LogToTransportsInput {
   data: Record<string, unknown>;
   level: LogLevel;
-  options: Options;
   request: Request;
   store: StoreData;
+  transports: Transport[];
 }
 
 export const logToTransports = (input: LogToTransportsInput): void => {
-  const { level, request, data, store, options } = input;
-  const transports = options.config?.transports ?? [];
+  const { level, request, data, store, transports } = input;
   if (transports.length === 0) {
     return;
   }