@pori15/logixlysia 6.0.11 → 6.0.13

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import { Elysia, SingletonBase } from "elysia";
+import { Logger as PinoLogger, LoggerOptions as PinoLoggerOptions } from "pino";
+interface ProblemDocument {
+	detail?: string;
+	instance?: string;
+	status?: number;
+	title: string;
+	type: string;
+	[key: string]: unknown;
+}
+/**
+* RFC 9457 Problem Details Error
+*
+* Core members:
+* - type: URI reference identifying the problem type (default "about:blank")
+* - title: Short human-readable summary
+* - status: HTTP status code
+* - detail: Human-readable explanation for this occurrence
+* - instance: URI reference identifying this specific occurrence
+* - extensions: Additional properties serialized as-is
+*/
+declare class ProblemError extends Error {
+	readonly status: number;
+	readonly title: string;
+	readonly type: string;
+	readonly detail?: string;
+	readonly instance?: string;
+	readonly extensions?: Record<string, unknown>;
+	constructor(type: string | undefined, title: string, status: number, detail?: string, instance?: string, extensions?: Record<string, unknown>);
+	toJSON(): ProblemDocument;
+}
+interface ProblemConfig {
+	detail?: string;
+	extensions?: Record<string, unknown>;
+	instance?: string;
+	title?: string;
+	type?: string;
+}
+/**
+* 工厂函数：根据 HTTP 状态码快速创建 ProblemError
+*
+* @example
+* throw createProblem(400, { detail: 'Invalid email' })
+* throw createProblem(409, { title: 'Duplicate', detail: 'Email already exists' })
+*/
+declare const createProblem: (status: number, overrides?: ProblemConfig) => ProblemError;
+type HttpErrorFactory = (detail?: string, extensions?: Record<string, unknown>) => ProblemError;
+interface HttpErrorConstructor {
+	BadGateway: HttpErrorFactory;
+	BadRequest: HttpErrorFactory;
+	Conflict: HttpErrorFactory;
+	Forbidden: HttpErrorFactory;
+	GatewayTimeout: HttpErrorFactory;
+	InternalServerError: HttpErrorFactory;
+	MethodNotAllowed: HttpErrorFactory;
+	NotAcceptable: HttpErrorFactory;
+	NotFound: HttpErrorFactory;
+	NotImplemented: HttpErrorFactory;
+	PaymentRequired: HttpErrorFactory;
+	ServiceUnavailable: HttpErrorFactory;
+	Unauthorized: HttpErrorFactory;
+}
+declare const HttpError: HttpErrorConstructor;
+type Code = number | "PROBLEM_ERROR" | "UNKNOWN" | "VALIDATION" | "NOT_FOUND" | "PARSE" | "INTERNAL_SERVER_ERROR" | "INVALID_COOKIE_SIGNATURE" | "INVALID_FILE_TYPE";
+/** Pino Logger 实例类型 */
+type Pino = PinoLogger<never, boolean>;
+/** 日志级别 */
+type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+/** 单次请求携带的计时和路径数据 */
+interface StoreData {
+	/** 请求开始的纳秒时间戳（hrtime） */
+	beforeTime: bigint;
+	/** 缓存的 URL pathname，避免重复解析 */
+	pathname: string;
+}
+/** Elysia store 中挂载的 logixlysia 状态 */
+interface LogixlysiaStore {
+	beforeTime?: bigint;
+	logger: Logger;
+	pathname?: string;
+	pino: Pino;
+	[key: string]: unknown;
+}
+/** 自定义日志传输接口（如 Elasticsearch、Slack 等） */
+interface Transport {
+	/**
+	* 接收一条日志并输出到外部系统
+	*
+	* @param level - 日志级别
+	* @param message - 日志消息
+	* @param meta - 附加元数据（请求信息、耗时等）
+	*/
+	log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void | Promise<void>;
+}
+/** 日志文件轮转配置 */
+interface LogRotationConfig {
+	/** 轮转后是否压缩旧文件 */
+	compress?: boolean;
+	/** 压缩算法 */
+	compression?: "gzip";
+	/** 固定间隔轮转，如 `'1d'`、`'12h'` */
+	interval?: string;
+	/** 保留的最大文件数量或时长，如 `10` 或 `'7d'` */
+	maxFiles?: number | string;
+	/** 单个日志文件最大体积，如 `'10m'`、`'5k'`，或字节数 */
+	maxSize?: string | number;
+}
+/** 错误码到 HTTP 响应的映射条目 */
+interface ErrorMapping {
+	/** 错误详情描述 */
+	detail?: string;
+	/** HTTP 状态码 */
+	status: number;
+	/** 错误标题 */
+	title: string;
+}
+/**
+* 自定义错误解析回调
+*
+* 返回 `ProblemError` 表示已处理，返回 `void` 交给下一层处理
+*/
+type ErrorResolver = (error: unknown, context: {
+	code: Code;
+	path: string;
+	request: Request;
+}) => ProblemError | void;
+/** 启动消息配置 */
+interface StartupConfig {
+	/** 启动消息格式，默认 `"banner"` */
+	format?: "simple" | "banner";
+	/** 是否显示启动消息，默认 `true` */
+	show?: boolean;
+}
+/** 日志格式配置 */
+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;
+}
+/** 文件日志配置 */
+interface FileConfig {
+	/** 日志文件路径（必填） */
+	path: string;
+	/** 日志轮转配置 */
+	rotation?: LogRotationConfig;
+}
+/** 自定义传输配置 */
+interface TransportsConfig {
+	/** 设为 `true` 时只使用 transports，禁用控制台和文件输出 */
+	only?: boolean;
+	/** 传输目标列表 */
+	targets: Transport[];
+}
+/** 错误处理配置 */
+interface ErrorConfig {
+	/** 错误码映射表（Postgres / MySQL / 自定义错误码） */
+	errorMap?: Record<string, ErrorMapping>;
+	/** 自定义错误解析回调 */
+	resolve?: ErrorResolver;
+	/** 自定义错误类型的 Base URL（RFC 9457） */
+	typeBaseUrl?: string;
+	/** 是否在控制台显示完整错误详情（detail、extensions），默认 `false` */
+	verbose?: boolean;
+}
+/** Logixlysia 插件配置 */
+interface Options {
+	/** 错误处理配置 */
+	error?: ErrorConfig;
+	/** 文件日志配置，设为 `false` 禁用文件日志 */
+	file?: false | FileConfig;
+	/** 日志格式配置 */
+	format?: FormatConfig;
+	/** 日志级别过滤，接受单个级别或级别数组 */
+	logLevel?: LogLevel | LogLevel[];
+	/** Pino Logger 原生配置透传 */
+	pino?: PinoLoggerOptions;
+	/** 启动消息配置 */
+	startup?: StartupConfig;
+	/** 自定义传输（数组或带 `only` 选项的对象） */
+	transports?: Transport[] | TransportsConfig;
+}
+/** Logger 实例，可通过 `store.logger` 访问 */
+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, context?: Record<string, unknown>) => void;
+}
+/** Logixlysia 请求上下文 */
+interface LogixlysiaContext {
+	request: Request;
+	store: LogixlysiaStore;
+}
+/**
+* 递归提取错误码
+* 沿 cause/error 链递归查找，支持被包装的底层错误（Postgres、MySQL、第三方库等）
+*/
+declare const getErrorCode: (error: unknown) => string | undefined;
+interface NormalizeOptions {
+	errorMap?: Record<string, ErrorMapping>;
+	request?: Request;
+	resolve?: ErrorResolver;
+	typeBaseUrl?: string;
+}
+declare const normalizeToProblem: (error: unknown, code: Code, path: string, options?: NormalizeOptions) => ProblemError;
+type Logixlysia = Elysia<"Logixlysia", SingletonBase & {
+	store: LogixlysiaStore;
+}>;
+declare const logixlysia: (options?: Options) => Logixlysia;
+export { normalizeToProblem, logixlysia, getErrorCode, logixlysia as default, createProblem, TransportsConfig, Transport, StoreData, StartupConfig, ProblemError, ProblemDocument, ProblemConfig, Pino, Options, LogixlysiaStore, LogixlysiaContext, Logixlysia, Logger, LogLevel, HttpErrorConstructor, HttpError, FormatConfig, FileConfig, ErrorResolver, ErrorMapping, ErrorConfig, Code };