@skax/logger 1.0.1 → 2.0.0-beta.1

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2023 Shine Shao
+Copyright (c) 2026 Shine Shao
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,48 +1,168 @@
-## @skax/logger
+# @skax/logger
 
-![build](https://github.com/freeshineit/skax-logger/workflows/build/badge.svg) ![Download](https://img.shields.io/npm/dm/@skax/logger.svg) ![Version](https://img.shields.io/npm/v/@skax/logger.svg) ![License](https://img.shields.io/npm/l/@skax/logger.svg)
+A lightweight, zero-dependency logger with **level filtering**, **module prefix**, and **caller-context output**.
 
-### Usage
+Uses `Proxy` + `Reflect` so DevTools source links point to the actual call site — not logger internals.
 
-```sh
-yarn add @skax/logger
+## Features
+
+- 🎚️ **Level filtering** — `NONE` / `ERROR` / `WARN` / `INFO` / `DEBUG`, switchable at runtime
+- 🏷️ **Module prefix** — each logger carries a `[ModuleName]` tag for easy identification
+- 📍 **Caller-context output** — browser DevTools link to the real call site, not `logger.ts:140`
+- 🪞 **Proxy-based dispatch** — zero-overhead: returns `NOOP` when the level suppresses output
+- 📦 **Tree-shakable** — ESM & CJS builds, no dependencies
+- 🌐 **UMD build** — drop-in `<script>` for browser usage
+
+## Installation
+
+```bash
+npm install @skax/logger
+```
+
+## Quick Start
+
+```ts
+import { Logger } from "@skax/logger";
+
+const logger = new Logger("MyModule", Logger.LEVEL.DEBUG);
+
+logger.info("Server started", { port: 3000 });
+// → [MyModule] [INFO] Server started { port: 3000 }
+
+logger.warn("Disk space low", { remaining: "2%" });
+// → [MyModule] [WARN] Disk space low { remaining: "2%" }
+
+logger.error("Connection failed", new Error("timeout"));
+// → [MyModule] [ERROR] Connection failed Error: timeout
+```
+
+## API
+
+### `new Logger(prefix?, level?)`
+
+Creates a new logger instance.
+
+| Parameter | Type     | Default             | Description                       |
+| --------- | -------- | ------------------- | --------------------------------- |
+| `prefix`  | `string` | `"Logger"`          | Module name shown in `[brackets]` |
+| `level`   | `Level`  | `Logger.LEVEL.WARN` | Minimum log level to output       |
+
+<br/>
+
+```ts
+const logger = new Logger("API", Logger.LEVEL.INFO);
+```
+
+### Log Levels
+
+Accessible via `Logger.LEVEL`:
+
+| Constant             | Value | Description                    |
+| -------------------- | ----- | ------------------------------ |
+| `Logger.LEVEL.NONE`  | `0`   | Suppress all output            |
+| `Logger.LEVEL.ERROR` | `1`   | Only errors                    |
+| `Logger.LEVEL.WARN`  | `2`   | Warnings and errors            |
+| `Logger.LEVEL.INFO`  | `3`   | Info, warnings, errors         |
+| `Logger.LEVEL.DEBUG` | `4`   | All messages (including debug) |
+
+### Methods
+
+```ts
+logger.error(...args); // Always output (unless level = NONE)
+logger.warn(...args); // Output when level ≥ WARN
+logger.info(...args); // Output when level ≥ INFO
+logger.debug(...args); // Output when level ≥ DEBUG
+logger.group(label); // console.group when level ≥ DEBUG
+logger.groupEnd(); // console.groupEnd when level ≥ DEBUG
+```
+
+### `setLevel(level)` / `getLevel()`
+
+Change or read the log level at runtime:
+
+```ts
+logger.setLevel(Logger.LEVEL.DEBUG); // enable all logs
+logger.setLevel(Logger.LEVEL.NONE); // silence everything
+
+console.log(logger.getLevel()); // 0
+```
+
+### `getLogger(debug?)`
+
+Returns a global singleton logger with prefix `"Logger"`:
+
+```ts
+import { getLogger } from "@skax/logger";
+
+const log = getLogger(true); // DEBUG level
+log.info("App initialized"); // → [Logger] [INFO] App initialized
 ```
 
+The singleton is lazily created on first call — subsequent calls return the same instance.
+
+### TypeScript
+
 ```ts
-import Logger from '@skax/logger';
+import { Logger } from "@skax/logger";
 
-const logger = new Logger();
+// The level type is inferred from Logger.LEVEL:
+const level: (typeof Logger.LEVEL)[keyof typeof Logger.LEVEL] = Logger.LEVEL.DEBUG;
 
-logger.d('console.debug print'); // debug
-logger.v('console.log print'); // log
-logger.i('console.info print'); // info
-logger.w('console.warn print'); // warn
-logger.e('console.error print'); // error
+// Or just let TS infer:
+const logger = new Logger("TSModule", Logger.LEVEL.INFO);
+logger.setLevel(Logger.LEVEL.DEBUG);
+const current = logger.getLevel(); // 0 | 1 | 2 | 3 | 4
 ```
 
-### umd
+## How It Works
+
+The constructor returns a **Proxy** that intercepts property access. When you call `logger.info(...)`:
+
+1. The Proxy's `get` trap checks `target._level >= Logger.LEVEL.INFO`
+2. If `true` → returns `console.info.bind(console, "[prefix] [INFO]")` — called in **your** stack frame
+3. If `false` → returns `Logger.NOOP` — a no-op function, zero cost
+
+```
+yourFile.ts:42  →  logger.info("hello")
+                     ↓
+              Proxy.get("info")
+                     ↓
+              console.info.bind(console, "[Demo] [INFO]")
+                     ↓
+              DevTools source → yourFile.ts:42 ✓
+```
+
+## Browser Usage (UMD)
 
 ```html
-<script src="./index.umd.js"></script>
+<script src="./node_modules/@skax/logger/dist/index.umd.js"></script>
 <script>
-  (function () {
-    const logger = new Logger();
+  const logger = new Logger("Browser", Logger.LEVEL.DEBUG);
+  logger.info("Hello from the browser!");
+</script>
+```
 
-    logger.v(logger.version());
+A live demo is included at [`public/index.html`](public/index.html).
 
-    logger.d('1234132');
-    logger.v('1234132');
-    logger.i('1234132');
-    logger.w('1234132');
-    logger.e('1234132');
+## Build
 
-    logger.setOptions({ level: 'WARN' });
+```bash
+npm run build      # Production build (CJS + ESM + UMD)
+npm run dev        # Development watch mode
+npm run test       # Run tests with coverage
+```
+
+Output:
 
-    logger.d('2-1234132');
-    logger.v('2-1234132');
-    logger.i('2-1234132');
-    logger.w('2-1234132');
-    logger.e('2-1234132');
-  })();
-</script>
 ```
+dist/
+├── index.cjs       # CommonJS
+├── index.esm.js    # ES Module
+├── index.umd.js    # UMD (browser)
+└── types/
+    └── index.d.ts  # TypeScript declarations
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,166 @@
+# @skax/logger
+
+轻量级、零依赖的日志工具，支持**分级过滤**、**模块前缀**和**调用者上下文输出**。
+
+通过 `Proxy` + `Reflect` 使得浏览器 DevTools 的源文件链接指向真正的调用位置，而非 logger 内部。
+
+## 特性
+
+- 🎚️ **分级过滤** — `NONE` / `ERROR` / `WARN` / `INFO` / `DEBUG`，运行时动态切换
+- 🏷️ **模块前缀** — 每个 logger 携带 `[模块名]` 标签，便于识别来源
+- 📍 **调用者上下文** — DevTools 源链接指向实际调用位置，而非 `logger.ts:140`
+- 🪞 **Proxy 分发** — 零开销：级别不满足时返回 `NOOP` 空函数
+- 📦 **Tree-shakable** — ESM & CJS 双构建，零依赖
+- 🌐 **UMD 构建** — 浏览器 `<script>` 直接引入
+
+## 安装
+
+```bash
+npm install @skax/logger
+```
+
+## 快速开始
+
+```ts
+import { Logger } from "@skax/logger";
+
+const logger = new Logger("MyModule", Logger.LEVEL.DEBUG);
+
+logger.info("服务启动", { port: 3000 });
+// → [MyModule] [INFO] 服务启动 { port: 3000 }
+
+logger.warn("磁盘空间不足", { remaining: "2%" });
+// → [MyModule] [WARN] 磁盘空间不足 { remaining: "2%" }
+
+logger.error("连接失败", new Error("超时"));
+// → [MyModule] [ERROR] 连接失败 Error: 超时
+```
+
+## API
+
+### `new Logger(prefix?, level?)`
+
+创建一个 logger 实例。
+
+| 参数     | 类型     | 默认值              | 说明                           |
+| -------- | -------- | ------------------- | ------------------------------ |
+| `prefix` | `string` | `"Logger"`          | 模块名称，显示在 `[方括号]` 中 |
+| `level`  | `Level`  | `Logger.LEVEL.WARN` | 最低输出级别                   |
+
+```ts
+const logger = new Logger("API", Logger.LEVEL.INFO);
+```
+
+### 日志等级
+
+通过 `Logger.LEVEL` 访问：
+
+| 常量                 | 值  | 说明                     |
+| -------------------- | --- | ------------------------ |
+| `Logger.LEVEL.NONE`  | `0` | 关闭所有日志             |
+| `Logger.LEVEL.ERROR` | `1` | 仅输出 error             |
+| `Logger.LEVEL.WARN`  | `2` | 输出 warn 及 error       |
+| `Logger.LEVEL.INFO`  | `3` | 输出 info、warn、error   |
+| `Logger.LEVEL.DEBUG` | `4` | 输出所有日志（含 debug） |
+
+### 日志方法
+
+```ts
+logger.error(...args); // 始终输出（除非 level = NONE）
+logger.warn(...args); // level ≥ WARN 时输出
+logger.info(...args); // level ≥ INFO 时输出
+logger.debug(...args); // level ≥ DEBUG 时输出
+logger.group(label); // level ≥ DEBUG 时调用 console.group
+logger.groupEnd(); // level ≥ DEBUG 时调用 console.groupEnd
+```
+
+### `setLevel(level)` / `getLevel()`
+
+运行时修改或读取日志级别：
+
+```ts
+logger.setLevel(Logger.LEVEL.DEBUG); // 开启所有日志
+logger.setLevel(Logger.LEVEL.NONE); // 关闭所有日志
+
+console.log(logger.getLevel()); // 0
+```
+
+### `getLogger(debug?)`
+
+返回全局单例 logger，前缀固定为 `"Logger"`：
+
+```ts
+import { getLogger } from "@skax/logger";
+
+const log = getLogger(true); // DEBUG 级别
+log.info("应用已初始化"); // → [Logger] [INFO] 应用已初始化
+```
+
+单例在首次调用时惰性创建——后续调用返回同一实例。
+
+### TypeScript
+
+```ts
+import { Logger } from "@skax/logger";
+
+// 级别类型从 Logger.LEVEL 推导：
+const level: (typeof Logger.LEVEL)[keyof typeof Logger.LEVEL] = Logger.LEVEL.DEBUG;
+
+// 或直接让 TS 推断：
+const logger = new Logger("TSModule", Logger.LEVEL.INFO);
+logger.setLevel(Logger.LEVEL.DEBUG);
+const current = logger.getLevel(); // 0 | 1 | 2 | 3 | 4
+```
+
+## 原理
+
+构造函数返回一个 **Proxy** 实例来拦截属性访问。调用 `logger.info(...)` 时：
+
+1. Proxy 的 `get` 陷阱检查 `target._level >= Logger.LEVEL.INFO`
+2. 满足条件 → 返回 `console.info.bind(console, "[前缀] [INFO]")` — 在**调用者**栈帧中执行
+3. 不满足 → 返回 `Logger.NOOP` — 空函数，零开销
+
+```
+yourFile.ts:42  →  logger.info("你好")
+                     ↓
+              Proxy.get("info")
+                     ↓
+              console.info.bind(console, "[Demo] [INFO]")
+                     ↓
+              DevTools 源链接 → yourFile.ts:42 ✓
+```
+
+## 浏览器使用 (UMD)
+
+```html
+<script src="./node_modules/@skax/logger/dist/index.umd.js"></script>
+<script>
+  const logger = new Logger("Browser", Logger.LEVEL.DEBUG);
+  logger.info("来自浏览器的问候！");
+</script>
+```
+
+在线演示：[`public/index.html`](public/index.html)
+
+## 构建
+
+```bash
+npm run build      # 生产构建（CJS + ESM + UMD）
+npm run dev        # 开发模式（watch）
+npm run test       # 运行测试（含覆盖率）
+```
+
+输出结构：
+
+```
+dist/
+├── index.cjs       # CommonJS
+├── index.esm.js    # ES Module
+├── index.umd.js    # UMD（浏览器）
+└── types/
+    └── index.d.ts  # TypeScript 类型声明
+```
+
+## 许可证
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,6 @@
+/*
+* @skax/logger v2.0.0-beta.1
+* Copyright (c) 2026-05-16 ShineShao <xiaoshaoqq@gmail.com>
+* Released under the MIT License.
+*/
+"use strict";var Logger=function(){function Logger(prefix,level){if(void 0===prefix&&(prefix="Logger"),void 0===level&&(level=Logger.LEVEL.WARN),this._prefix=prefix,this._level=level,"function"==typeof Proxy&&"object"==("undefined"==typeof Reflect?"undefined":(obj=Reflect)&&"undefined"!=typeof Symbol&&obj.constructor===Symbol?"symbol":typeof obj))return new Proxy(this,{get:function(target,prop,receiver){var value=Reflect.get(target,prop,receiver);if("setLevel"===prop||"getLevel"===prop)return"function"==typeof value?value.bind(target):value;if("string"==typeof prop&&prop.startsWith("_"))return value;switch(prop){case"error":return target._level>=Logger.LEVEL.ERROR?function(){}.bind():Logger.NOOP;case"warn":return target._level>=Logger.LEVEL.WARN?function(){}.bind():Logger.NOOP;case"info":return target._level>=Logger.LEVEL.INFO?function(){}.bind():Logger.NOOP;case"debug":case"group":case"groupEnd":return target._level>=Logger.LEVEL.DEBUG?function(){}.bind():Logger.NOOP;default:return value}}});var obj}var _proto=Logger.prototype;return _proto.setLevel=function(level){this._level=level},_proto.getLevel=function(){return this._level},_proto.error=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.ERROR&&(_console=console).error.apply(_console,[].concat(["["+this._prefix+"] [ERROR]"],_args))},_proto.warn=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.WARN&&(_console=console).warn.apply(_console,[].concat(["["+this._prefix+"] [WARN]"],_args))},_proto.info=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.INFO&&(_console=console).info.apply(_console,[].concat(["["+this._prefix+"] [INFO]"],_args))},_proto.debug=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.DEBUG&&(_console=console).debug.apply(_console,[].concat(["["+this._prefix+"] [DEBUG]"],_args))},_proto.group=function(_label){this._level,Logger.LEVEL.DEBUG},_proto.groupEnd=function(){this._level,Logger.LEVEL.DEBUG},Logger}();Logger.NOOP=function(){},Logger.LEVEL={NONE:0,ERROR:1,WARN:2,INFO:3,DEBUG:4};var __$Default_Logger$__=null;exports.Logger=Logger,exports.getLogger=function(debug){return void 0===debug&&(debug=!1),__$Default_Logger$__||(__$Default_Logger$__=new Logger("Logger",debug?Logger.LEVEL.DEBUG:Logger.LEVEL.WARN)),__$Default_Logger$__};

package/dist/index.esm.js

@@ -0,0 +1,6 @@
+/*
+* @skax/logger v2.0.0-beta.1
+* Copyright (c) 2026-05-16 ShineShao <xiaoshaoqq@gmail.com>
+* Released under the MIT License.
+*/
+var Logger=function(){function Logger(prefix,level){if(void 0===prefix&&(prefix="Logger"),void 0===level&&(level=Logger.LEVEL.WARN),this._prefix=prefix,this._level=level,"function"==typeof Proxy&&"object"==("undefined"==typeof Reflect?"undefined":(obj=Reflect)&&"undefined"!=typeof Symbol&&obj.constructor===Symbol?"symbol":typeof obj))return new Proxy(this,{get:function(target,prop,receiver){var value=Reflect.get(target,prop,receiver);if("setLevel"===prop||"getLevel"===prop)return"function"==typeof value?value.bind(target):value;if("string"==typeof prop&&prop.startsWith("_"))return value;switch(prop){case"error":return target._level>=Logger.LEVEL.ERROR?function(){}.bind():Logger.NOOP;case"warn":return target._level>=Logger.LEVEL.WARN?function(){}.bind():Logger.NOOP;case"info":return target._level>=Logger.LEVEL.INFO?function(){}.bind():Logger.NOOP;case"debug":case"group":case"groupEnd":return target._level>=Logger.LEVEL.DEBUG?function(){}.bind():Logger.NOOP;default:return value}}});var obj}var _proto=Logger.prototype;return _proto.setLevel=function(level){this._level=level},_proto.getLevel=function(){return this._level},_proto.error=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.ERROR&&(_console=console).error.apply(_console,[].concat(["["+this._prefix+"] [ERROR]"],_args))},_proto.warn=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.WARN&&(_console=console).warn.apply(_console,[].concat(["["+this._prefix+"] [WARN]"],_args))},_proto.info=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.INFO&&(_console=console).info.apply(_console,[].concat(["["+this._prefix+"] [INFO]"],_args))},_proto.debug=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.DEBUG&&(_console=console).debug.apply(_console,[].concat(["["+this._prefix+"] [DEBUG]"],_args))},_proto.group=function(_label){this._level,Logger.LEVEL.DEBUG},_proto.groupEnd=function(){this._level,Logger.LEVEL.DEBUG},Logger}();Logger.NOOP=function(){},Logger.LEVEL={NONE:0,ERROR:1,WARN:2,INFO:3,DEBUG:4};var __$Default_Logger$__=null;function getLogger(debug){return void 0===debug&&(debug=!1),__$Default_Logger$__||(__$Default_Logger$__=new Logger("Logger",debug?Logger.LEVEL.DEBUG:Logger.LEVEL.WARN)),__$Default_Logger$__}export{Logger,getLogger};

package/dist/index.umd.js

@@ -0,0 +1,6 @@
+/*
+* @skax/logger v2.0.0-beta.1
+* Copyright (c) 2026-05-16 ShineShao <xiaoshaoqq@gmail.com>
+* Released under the MIT License.
+*/
+!function(global,factory){"object"==typeof exports&&"undefined"!=typeof module?module.exports=factory():"function"==typeof define&&define.amd?define(factory):(global="undefined"!=typeof globalThis?globalThis:global||self).Logger=factory()}(this,function(){"use strict";var Logger=function(){function Logger(prefix,level){if(void 0===prefix&&(prefix="Logger"),void 0===level&&(level=Logger.LEVEL.WARN),this._prefix=prefix,this._level=level,"function"==typeof Proxy&&"object"==("undefined"==typeof Reflect?"undefined":(obj=Reflect)&&"undefined"!=typeof Symbol&&obj.constructor===Symbol?"symbol":typeof obj))return new Proxy(this,{get:function(target,prop,receiver){var value=Reflect.get(target,prop,receiver);if("setLevel"===prop||"getLevel"===prop)return"function"==typeof value?value.bind(target):value;if("string"==typeof prop&&prop.startsWith("_"))return value;switch(prop){case"error":return target._level>=Logger.LEVEL.ERROR?function(){}.bind():Logger.NOOP;case"warn":return target._level>=Logger.LEVEL.WARN?function(){}.bind():Logger.NOOP;case"info":return target._level>=Logger.LEVEL.INFO?function(){}.bind():Logger.NOOP;case"debug":case"group":case"groupEnd":return target._level>=Logger.LEVEL.DEBUG?function(){}.bind():Logger.NOOP;default:return value}}});var obj}var _proto=Logger.prototype;return _proto.setLevel=function(level){this._level=level},_proto.getLevel=function(){return this._level},_proto.error=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.ERROR&&(_console=console).error.apply(_console,[].concat(["["+this._prefix+"] [ERROR]"],_args))},_proto.warn=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.WARN&&(_console=console).warn.apply(_console,[].concat(["["+this._prefix+"] [WARN]"],_args))},_proto.info=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.INFO&&(_console=console).info.apply(_console,[].concat(["["+this._prefix+"] [INFO]"],_args))},_proto.debug=function(){for(var _len=arguments.length,_args=new Array(_len),_key=0;_key<_len;_key++)_args[_key]=arguments[_key];var _console;this._level>=Logger.LEVEL.DEBUG&&(_console=console).debug.apply(_console,[].concat(["["+this._prefix+"] [DEBUG]"],_args))},_proto.group=function(_label){this._level,Logger.LEVEL.DEBUG},_proto.groupEnd=function(){this._level,Logger.LEVEL.DEBUG},Logger}();return Logger.NOOP=function(){},Logger.LEVEL={NONE:0,ERROR:1,WARN:2,INFO:3,DEBUG:4},Logger});

package/dist/types/index.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Lightweight logger with level filtering, module prefix, and caller-context output.
+ *
+ * Uses Proxy + Reflect so that `console.error/warn/info/debug` are invoked in the
+ * **caller's** stack frame, not inside logger.ts.  The browser DevTools source link
+ * will point to the actual call site (e.g. `fetcher.ts:411`) rather than
+ * `logger.ts:140`.
+ *
+ * 轻量级日志工具，支持分级过滤、模块前缀、调用者上下文输出。
+ *
+ * 通过 Proxy + Reflect 使得 `console.error/warn/info/debug` 在**调用者**的
+ * 栈帧中执行。浏览器 DevTools 的源文件链接会指向真正的调用位置
+ * （如 `fetcher.ts:411`），而不是 `logger.ts:140`。
+ *
+ * @module
+ * @example
+ * ```ts
+ * import { Logger } from "@skax/logger";
+ *
+ * const logger = new Logger("MyModule", Logger.LEVEL.DEBUG);
+ * logger.info("服务启动", { port: 3000 });
+ * // [MyModule] [INFO] 服务启动 { port: 3000 }
+ * // ↑ DevTools source: the actual file that called logger.info
+ * ```
+ */
+/**
+ * 日志记录器。
+ *
+ * 构造时返回 Proxy 实例，对 `logger.xxx()` 的每次调用都在**调用者**的栈帧中执行
+ * `console.xxx`，因此浏览器 DevTools 的源文件链接指向业务代码而非本文件。
+ *
+ * 当 Proxy 不可用时（如极端旧环境），降级为普通方法调用。
+ *
+ * @class
+ * @example
+ * ```ts
+ * const logger = new Logger("Logger");
+ * logger.info("playlist loaded");
+ * ```
+ */
+declare class Logger {
+    /**
+     * 空函数，当日志级别不满足条件时替代真正的 console 方法，避免无效调用。
+     *
+     * 每个被抑制的日志方法调用都会返回此函数，调用者执行它时不会有任何副作用。
+     *
+     * Empty function used as noop when the log level suppresses output.
+     * Every suppressed log method returns this function — calling it is a true no-op.
+     *
+     * @public
+     */
+    static NOOP: () => void;
+    /**
+     * 日志等级常量（数字枚举对象）。
+     *
+     * 使用 `as const` 断言保留字面量类型，便于 TS 推导出联合类型
+     * `0 | 1 | 2 | 3 | 4`，同时作为静态属性暴露供外部使用。
+     *
+     * | 常量 | 值 | 说明 |
+     * |------|----|------|
+     * | `Logger.LEVEL.NONE`  | `0` | 关闭所有日志 |
+     * | `Logger.LEVEL.ERROR` | `1` | 仅输出 error |
+     * | `Logger.LEVEL.WARN`  | `2` | 输出 warn 及更高级别 |
+     * | `Logger.LEVEL.INFO`  | `3` | 输出 info 及更高级别 |
+     * | `Logger.LEVEL.DEBUG` | `4` | 输出所有日志（含 debug） |
+     *
+     * Log level constants declared with `as const` so TypeScript
+     * infers literal types, enabling the union `0 | 1 | 2 | 3 | 4`.
+     *
+     * | Constant | Value | Description |
+     * |----------|-------|-------------|
+     * | `Logger.LEVEL.NONE`   | `0`   | Suppress all output |
+     * | `Logger.LEVEL.ERROR`  | `1`   | Only errors |
+     * | `Logger.LEVEL.WARN`   | `2`   | Warnings and above |
+     * | `Logger.LEVEL.INFO`   | `3`   | Info and above |
+     * | `Logger.LEVEL.DEBUG`  | `4`   | All messages (including debug) |
+     *
+     * @public
+     */
+    static LEVEL: {
+        /** 关闭所有日志 */
+        readonly NONE: 0;
+        /** 仅输出 error */
+        readonly ERROR: 1;
+        /** 输出 warn 及更高级别 */
+        readonly WARN: 2;
+        /** 输出 info 及更高级别 */
+        readonly INFO: 3;
+        /** 输出所有日志（含 debug） */
+        readonly DEBUG: 4;
+    };
+    /**
+     * 当前日志级别。只有 ≥ 此级别的日志方法才会真正输出。
+     *
+     * @private
+     */
+    private _level;
+    /**
+     * 模块前缀，显示在每条日志的 `[前缀]` 中，用于区分不同模块的输出。
+     *
+     * @private
+     */
+    private _prefix;
+    /**
+     * 创建一个 Logger 实例。
+     *
+     * 在支持 Proxy 的环境中，构造函数返回 Proxy 实例而非 `this`。
+     * Proxy 拦截所有属性访问，按需返回绑定了前缀的 `console.*` 函数或空函数。
+     *
+     * @param {string}  [prefix="Logger"] - 模块前缀，显示在 `[方括号]` 中
+     * @param {number}  [level=Logger.LEVEL.WARN] - 最低输出级别，低于此级别的日志会被抑制
+     *
+     * @example
+     * ```ts
+     * // 默认 WARN 级别，只输出 error 和 warn
+     * const logger = new Logger("Logger");
+     *
+     * // DEBUG 级别，输出所有日志
+     * const debugLogger = new Logger("Debug", Logger.LEVEL.DEBUG);
+     * ```
+     */
+    constructor(prefix?: string, level?: (typeof Logger.LEVEL)[keyof typeof Logger.LEVEL]);
+    /**
+     * 动态设置日志级别。
+     *
+     * 调用后立即生效——已抑制的日志方法会变为 NOOP，已启用的会恢复输出。
+     *
+     * @param {number} level - 新的日志级别，使用 `Logger.LEVEL.XXX` 常量
+     *
+     * @example
+     * ```ts
+     * logger.setLevel(Logger.LEVEL.DEBUG); // 开启全部日志
+     * logger.setLevel(Logger.LEVEL.NONE);  // 关闭全部日志
+     * ```
+     */
+    setLevel(level: (typeof Logger.LEVEL)[keyof typeof Logger.LEVEL]): void;
+    /**
+     * 获取当前日志级别。
+     *
+     * @returns {number} 当前日志级别（0 | 1 | 2 | 3 | 4）
+     *
+     * @example
+     * ```ts
+     * if (logger.getLevel() === Logger.LEVEL.DEBUG) {
+     *   logger.info("调试模式已开启");
+     * }
+     * ```
+     */
+    getLevel(): (typeof Logger.LEVEL)[keyof typeof Logger.LEVEL];
+    /**
+     * 输出错误日志。
+     *
+     * 当 `level ≥ ERROR` 时输出到 `console.error`，带 `[prefix] [ERROR]` 前缀。
+     *
+     * @param {...unknown} _args - 任意参数，原样传递给 console.error
+     *
+     * @example
+     * ```ts
+     * logger.error("请求失败", { status: 500 });
+     * // → [Logger] [ERROR] 请求失败 { status: 500 }
+     * ```
+     */
+    error(..._args: unknown[]): void;
+    /**
+     * 输出警告日志。
+     *
+     * 当 `level ≥ WARN` 时输出到 `console.warn`，带 `[prefix] [WARN]` 前缀。
+     *
+     * @param {...unknown} _args - 任意参数
+     *
+     * @example
+     * ```ts
+     * logger.warn("配置项缺失，使用默认值", { key: "timeout" });
+     * // → [Logger] [WARN] 配置项缺失，使用默认值 { key: "timeout" }
+     * ```
+     */
+    warn(..._args: unknown[]): void;
+    /**
+     * 输出信息日志。
+     *
+     * 当 `level ≥ INFO` 时输出到 `console.info`，带 `[prefix] [INFO]` 前缀。
+     *
+     * @param {...unknown} _args - 任意参数
+     *
+     * @example
+     * ```ts
+     * logger.info("服务启动", { port: 3000 });
+     * // → [Logger] [INFO] 服务启动 { port: 3000 }
+     * ```
+     */
+    info(..._args: unknown[]): void;
+    /**
+     * 输出调试日志。
+     *
+     * 当 `level ≥ DEBUG` 时输出到 `console.debug`，带 `[prefix] [DEBUG]` 前缀。
+     *
+     * @param {...unknown} _args - 任意参数
+     *
+     * @example
+     * ```ts
+     * logger.debug("请求详情", { method: "POST", payload: { id: 1 } });
+     * // → [Logger] [DEBUG] 请求详情 { method: "POST", payload: { id: 1 } }
+     * ```
+     */
+    debug(..._args: unknown[]): void;
+    /**
+     * 开始一个可折叠的日志分组（浏览器 console.group）。
+     *
+     * 当 `level ≥ DEBUG` 时调用 `console.group`，此后直到 `groupEnd()` 的日志
+     * 会嵌套在该分组内。
+     *
+     * @param {string} _label - 分组标题
+     *
+     * @example
+     * ```ts
+     * logger.group("批量处理");
+     * logger.debug("步骤 1");
+     * logger.debug("步骤 2");
+     * logger.groupEnd();
+     * ```
+     */
+    group(_label: string): void;
+    /**
+     * 结束当前日志分组（浏览器 console.groupEnd）。
+     *
+     * 当 `level ≥ DEBUG` 时调用 `console.groupEnd`。
+     *
+     * @example
+     * ```ts
+     * logger.groupEnd();
+     * ```
+     */
+    groupEnd(): void;
+}
+/**
+ * 获取全局共享的 Logger 单例。
+ *
+ * 惰性初始化：首次调用时创建实例，后续调用返回同一对象。
+ * 前缀固定为 `"Logger"`。
+ *
+ * @param {boolean} [debug=false] - 是否开启 DEBUG 模式。`true` 时级别为 DEBUG，否则为 WARN
+ * @returns {Logger} 全局唯一的 Logger 实例
+ *
+ * @example
+ * ```ts
+ * import { getLogger } from "@skax/logger";
+ *
+ * // 生产环境：默认 WARN 级别
+ * const log = getLogger();
+ *
+ * // 开发环境：DEBUG 级别
+ * const debugLog = getLogger(true);
+ *
+ * // 两次调用返回同一实例
+ * console.log(getLogger() === getLogger()); // true
+ * ```
+ */
+declare function getLogger(debug?: boolean): Logger;
+
+export { Logger, getLogger };

package/package.json

@@ -1,25 +1,78 @@
 {
   "name": "@skax/logger",
-  "version": "1.0.1",
-  "description": "console logger",
-  "main": "index.js",
-  "umd": "index.umd.js",
-  "types": "types/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/freeshineit/skax-logger.git"
+  "version": "2.0.0-beta.1",
+  "description": "A lightweight logger with level filtering, module prefix, and caller-context output.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.esm.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.cjs"
+    },
+    "./dist/index.umd.js": "./dist/index.umd.js",
+    "./dist/index.umd": "./dist/index.umd.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "npm run clean && cross-env NODE_ENV=development rollup --config rollup.config.mjs --watch",
+    "build": "npm run clean && cross-env NODE_ENV=production rollup --config rollup.config.mjs",
+    "clean": "rimraf dist",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "eslint --fix \"./src/**/*.{ts,tsx,js,jsx,mjs,vue,cjs}\"",
+    "lint:check": "eslint \"./src/**/*.{ts,tsx,js,jsx,mjs,vue,cjs}\"",
+    "fmt": "prettier --write \"./**/*.{ts,tsx,js,jsx,mjs,json,md,yml,yaml,vue,cjs,css,scss,sass}\"",
+    "fmt:check": "prettier --check \"./**/*.{ts,tsx,js,jsx,mjs,json,md,yml,yaml,vue,cjs,css,scss,sass}\"",
+    "docs": "typedoc",
+    "prepare": "husky"
   },
   "keywords": [
     "logger",
-    "console"
+    "logging",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "typescript",
+    "javascript"
   ],
   "author": "ShineShao <xiaoshaoqq@gmail.com>",
   "license": "MIT",
+  "devDependencies": {
+    "@commitlint/cli": "^20.2.0",
+    "@commitlint/config-conventional": "^20.2.0",
+    "pretty-quick": "^4.2.2",
+    "@skax/rollup-config": "^1.0.2",
+    "@types/jest": "^29.5.11",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.4",
+    "eslint-config-xx": "^2.2.4",
+    "http-server": "^14.1.1",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.8.1",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.60.2",
+    "ts-jest": "^29.1.1",
+    "tslib": "^2.6.2",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-mdn-links": "^5.0.10",
+    "typedoc-plugin-rename-defaults": "^0.7.3",
+    "typedoc-plugin-replace-text": "^4.2.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freeshineit/logger.git"
+  },
   "bugs": {
-    "url": "https://github.com/freeshineit/skax-logger/issues"
+    "url": "https://github.com/freeshineit/logger/issues"
   },
-  "homepage": "https://github.com/freeshineit/skax-logger#readme",
-  "engines": {
-    "node": ">=16"
-  }
-}
+  "homepage": "https://github.com/freeshineit/logger#readme"
+}

package/index.js

@@ -1,162 +0,0 @@
-/*
-*
-* @skax/logger.js v1.0.1
-* Copyright (c) 2023-9-30 ShineShao <xiaoshaoqq@gmail.com>
-* Released under the MIT License.
-*
-*/
-'use strict';
-
-/**
- * @class Logger
- * @classdesc Provide multiple log printing methods
- * @example
- * const logger = new Logger({})
- * logger.v("verbose log")
- */
-var Logger = /** @class */ (function () {
-    function Logger(options) {
-        if (options === void 0) { options = {}; }
-        this._options = {};
-        this._levelNum = 0;
-        /**
-         * @description  Method used to print error logs
-         * @method
-         *
-         * @example
-         * logger.e("error message") // error message
-         *
-         * @param {...any[]} args error messages
-         * @returns {void}
-         */
-        this.e = this._loggerFactory('error', this._levelNum <= 4);
-        /**
-         * @description Method used to print warn logs
-         * @method
-         *
-         * @example
-         * logger.w("warn message") // warn message
-         *
-         * @param {...any[]} args warn messages
-         * @returns {void}
-         */
-        this.w = this._loggerFactory('warn', this._levelNum <= 3);
-        /**
-         * @description Method used to print info logs
-         * @method
-         *
-         * @example
-         * logger.i("info message") // info message
-         *
-         * @param {...any[]} args info messages
-         * @returns {void}
-         */
-        this.i = this._loggerFactory('info', this._levelNum <= 2);
-        /**
-         * @description Method used to print verbose logs
-         * @method
-         *
-         * @example
-         * logger.v("verbose message") // verbose message
-         *
-         * @param {...any[]} args verbose messages
-         * @returns {void}
-         */
-        this.v = this._loggerFactory('log', this._levelNum <= 1);
-        /**
-         * @description Method used to print debug logs
-         * @method
-         *
-         * @example
-         * logger.d("debug message") // debug message
-         *
-         * @param {...any[]} msg debug messages
-         * @returns {void}
-         */
-        this.d = this._loggerFactory('debug', this._levelNum < 1);
-        this.setOptions(options);
-    }
-    /**
-     * @description  Method used to set logger option and change logger level
-     *
-     * @example
-     * logger.setOptions({level: 'INFO'}) // set logger level
-     *
-     * @param {LoggerOptions} options logger options
-     * @return {void}
-     */
-    Logger.prototype.setOptions = function (options) {
-        this._options = options;
-        this._levelNum = this._matchLevel(options.level || 'DEBUG');
-        if (this._levelNum !== 0) {
-            this.e = this._loggerFactory('error', this._levelNum <= 4);
-            this.w = this._loggerFactory('warn', this._levelNum <= 3);
-            this.i = this._loggerFactory('info', this._levelNum <= 2);
-            this.v = this._loggerFactory('log', this._levelNum <= 1);
-            this.d = this._loggerFactory('warn', this._levelNum < 1);
-        }
-    };
-    /**
-     * @description Private method used to match logger level
-     * @private
-     *
-     * @example
-     * this._matchLevel("DEBUG") // 0
-     *
-     * @param {LoggerLevel} level logger level
-     * @return {number}
-     */
-    Logger.prototype._matchLevel = function (level) {
-        var logLevel = 0;
-        switch (level) {
-            case 'DEBUG':
-                logLevel = 0;
-                break;
-            case 'VERBOSE':
-                logLevel = 1;
-                break;
-            case 'INFO':
-                logLevel = 2;
-                break;
-            case 'WARN':
-                logLevel = 3;
-                break;
-            case 'ERROR':
-                logLevel = 4;
-                break;
-        }
-        return logLevel;
-    };
-    /**
-     * @private
-     * @description Logger factory
-     * @param {ConsoleKey} type
-     * @param {boolean} bool
-     * @returns
-     */
-    Logger.prototype._loggerFactory = function (type, bool) {
-        var func = console[type];
-        if (bool && func) {
-            return func.bind(console, "[".concat(type.toLocaleUpperCase(), "]"));
-        }
-        return Logger.noop;
-    };
-    /**
-     * @description Get options
-     * @returns {LoggerOptions}
-     */
-    Logger.prototype.getOptions = function () {
-        return this._options;
-    };
-    /**
-     * @description Get version
-     * @returns {string}
-     */
-    Logger.prototype.version = function () {
-        return '1.0.1';
-    };
-    Logger.noop = function () { };
-    return Logger;
-}());
-
-module.exports = Logger;

package/index.umd.js

@@ -1,168 +0,0 @@
-/*
-*
-* @skax/logger.js v1.0.1
-* Copyright (c) 2023-9-30 ShineShao <xiaoshaoqq@gmail.com>
-* Released under the MIT License.
-*
-*/
-(function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
-    typeof define === 'function' && define.amd ? define(factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.Logger = factory());
-})(this, (function () { 'use strict';
-
-    /**
-     * @class Logger
-     * @classdesc Provide multiple log printing methods
-     * @example
-     * const logger = new Logger({})
-     * logger.v("verbose log")
-     */
-    var Logger = /** @class */ (function () {
-        function Logger(options) {
-            if (options === void 0) { options = {}; }
-            this._options = {};
-            this._levelNum = 0;
-            /**
-             * @description  Method used to print error logs
-             * @method
-             *
-             * @example
-             * logger.e("error message") // error message
-             *
-             * @param {...any[]} args error messages
-             * @returns {void}
-             */
-            this.e = this._loggerFactory('error', this._levelNum <= 4);
-            /**
-             * @description Method used to print warn logs
-             * @method
-             *
-             * @example
-             * logger.w("warn message") // warn message
-             *
-             * @param {...any[]} args warn messages
-             * @returns {void}
-             */
-            this.w = this._loggerFactory('warn', this._levelNum <= 3);
-            /**
-             * @description Method used to print info logs
-             * @method
-             *
-             * @example
-             * logger.i("info message") // info message
-             *
-             * @param {...any[]} args info messages
-             * @returns {void}
-             */
-            this.i = this._loggerFactory('info', this._levelNum <= 2);
-            /**
-             * @description Method used to print verbose logs
-             * @method
-             *
-             * @example
-             * logger.v("verbose message") // verbose message
-             *
-             * @param {...any[]} args verbose messages
-             * @returns {void}
-             */
-            this.v = this._loggerFactory('log', this._levelNum <= 1);
-            /**
-             * @description Method used to print debug logs
-             * @method
-             *
-             * @example
-             * logger.d("debug message") // debug message
-             *
-             * @param {...any[]} msg debug messages
-             * @returns {void}
-             */
-            this.d = this._loggerFactory('debug', this._levelNum < 1);
-            this.setOptions(options);
-        }
-        /**
-         * @description  Method used to set logger option and change logger level
-         *
-         * @example
-         * logger.setOptions({level: 'INFO'}) // set logger level
-         *
-         * @param {LoggerOptions} options logger options
-         * @return {void}
-         */
-        Logger.prototype.setOptions = function (options) {
-            this._options = options;
-            this._levelNum = this._matchLevel(options.level || 'DEBUG');
-            if (this._levelNum !== 0) {
-                this.e = this._loggerFactory('error', this._levelNum <= 4);
-                this.w = this._loggerFactory('warn', this._levelNum <= 3);
-                this.i = this._loggerFactory('info', this._levelNum <= 2);
-                this.v = this._loggerFactory('log', this._levelNum <= 1);
-                this.d = this._loggerFactory('warn', this._levelNum < 1);
-            }
-        };
-        /**
-         * @description Private method used to match logger level
-         * @private
-         *
-         * @example
-         * this._matchLevel("DEBUG") // 0
-         *
-         * @param {LoggerLevel} level logger level
-         * @return {number}
-         */
-        Logger.prototype._matchLevel = function (level) {
-            var logLevel = 0;
-            switch (level) {
-                case 'DEBUG':
-                    logLevel = 0;
-                    break;
-                case 'VERBOSE':
-                    logLevel = 1;
-                    break;
-                case 'INFO':
-                    logLevel = 2;
-                    break;
-                case 'WARN':
-                    logLevel = 3;
-                    break;
-                case 'ERROR':
-                    logLevel = 4;
-                    break;
-            }
-            return logLevel;
-        };
-        /**
-         * @private
-         * @description Logger factory
-         * @param {ConsoleKey} type
-         * @param {boolean} bool
-         * @returns
-         */
-        Logger.prototype._loggerFactory = function (type, bool) {
-            var func = console[type];
-            if (bool && func) {
-                return func.bind(console, "[".concat(type.toLocaleUpperCase(), "]"));
-            }
-            return Logger.noop;
-        };
-        /**
-         * @description Get options
-         * @returns {LoggerOptions}
-         */
-        Logger.prototype.getOptions = function () {
-            return this._options;
-        };
-        /**
-         * @description Get version
-         * @returns {string}
-         */
-        Logger.prototype.version = function () {
-            return '1.0.1';
-        };
-        Logger.noop = function () { };
-        return Logger;
-    }());
-
-    return Logger;
-
-}));

package/types/index.d.ts

@@ -1,116 +0,0 @@
-/** logger level */
-export type LoggerLevel = 'DEBUG' | 'VERBOSE' | 'INFO' | 'WARN' | 'ERROR';
-/** logger options */
-export interface LoggerOptions {
-    /** logger level */
-    level?: LoggerLevel;
-}
-export type LoggerFunc = (...data: any[]) => void;
-/**
- * @class Logger
- * @classdesc Provide multiple log printing methods
- * @example
- * const logger = new Logger({})
- * logger.v("verbose log")
- */
-declare class Logger {
-    private static readonly noop;
-    private _options;
-    private _levelNum;
-    constructor(options?: LoggerOptions);
-    /**
-     * @description  Method used to print error logs
-     * @method
-     *
-     * @example
-     * logger.e("error message") // error message
-     *
-     * @param {...any[]} args error messages
-     * @returns {void}
-     */
-    e: LoggerFunc;
-    /**
-     * @description Method used to print warn logs
-     * @method
-     *
-     * @example
-     * logger.w("warn message") // warn message
-     *
-     * @param {...any[]} args warn messages
-     * @returns {void}
-     */
-    w: LoggerFunc;
-    /**
-     * @description Method used to print info logs
-     * @method
-     *
-     * @example
-     * logger.i("info message") // info message
-     *
-     * @param {...any[]} args info messages
-     * @returns {void}
-     */
-    i: LoggerFunc;
-    /**
-     * @description Method used to print verbose logs
-     * @method
-     *
-     * @example
-     * logger.v("verbose message") // verbose message
-     *
-     * @param {...any[]} args verbose messages
-     * @returns {void}
-     */
-    v: LoggerFunc;
-    /**
-     * @description Method used to print debug logs
-     * @method
-     *
-     * @example
-     * logger.d("debug message") // debug message
-     *
-     * @param {...any[]} msg debug messages
-     * @returns {void}
-     */
-    d: LoggerFunc;
-    /**
-     * @description  Method used to set logger option and change logger level
-     *
-     * @example
-     * logger.setOptions({level: 'INFO'}) // set logger level
-     *
-     * @param {LoggerOptions} options logger options
-     * @return {void}
-     */
-    setOptions(options: Partial<LoggerOptions>): void;
-    /**
-     * @description Private method used to match logger level
-     * @private
-     *
-     * @example
-     * this._matchLevel("DEBUG") // 0
-     *
-     * @param {LoggerLevel} level logger level
-     * @return {number}
-     */
-    private _matchLevel;
-    /**
-     * @private
-     * @description Logger factory
-     * @param {ConsoleKey} type
-     * @param {boolean} bool
-     * @returns
-     */
-    private _loggerFactory;
-    /**
-     * @description Get options
-     * @returns {LoggerOptions}
-     */
-    getOptions(): Partial<LoggerOptions>;
-    /**
-     * @description Get version
-     * @returns {string}
-     */
-    version(): string;
-}
-export default Logger;