@wiajs/core 1.2.3 → 2.1.0

package/dist/core.mjs

@@ -1,5 +1,5 @@
 /*!
-  * wia core v1.2.3
+  * wia core v2.1.0
   * (c) 2015-2026 Sibyl Yu and contributors
   * Released under the MIT License.
   */
@@ -2073,227 +2073,193 @@ class Event {
   }
 }
 
-/*!
-  * wia util v3.4.25
-  * (c) 2018-2024 Yan (Sibyl) Yu and Yuxi (Evan) You and wia/vue contributors
-  * Released under the MIT License.
-  */
 /**
- * Created by way on 10/6/16.
- * Part of the code comes from @vue/shared
+ * @typedef {Object} LogOptions
+ * @property {string} m - 模块名称
+ */
+
+/**
+ * @typedef {((...args: any[]) => void) & { debug: (...args: any[])=>void, info: (...args: any[])=>void, warn: (...args: any[])=>void, error: (...args: any[])=>void, err: (...args: any[])=>void }} ScopedLogger
  */
 
-
 /**
- * 前端日志输出，封装 console日志，简化代码，支持模块或直接输出
- * 调用时，描述字符串后置，便于可选缺省，输出时，自带前置，类似 后端pino，保持前后端一致性
- * m 为模块，fn 为函数名称
+ * @typedef {((...args: any[]) => void) & { log: (...args: any[])=>void, debug: (...args: any[])=>void, info: (...args: any[])=>void, warn: (...args: any[])=>void, error: (...args: any[])=>void, err: (...args: any[])=>void, fn: (name: string) => ScopedLogger }} LoggerFn
+ */
+
+// 1. 安全地获取开发环境状态（兼容打包工具、浏览器和 Node.js）
+// 如果 Rspack 注入了 __DEV__，就用注入的值；如果是在 Node.js 下，就回退读取 "production"
+const isDev = typeof __DEV__ !== 'undefined' ? __DEV__ : "production" !== 'production';
+
+/**
+ * 前端日志输出，封装 console 日志，简化代码
+ * 自动识别并重排提示符与对象，保持前后端一致性
  */
 class Log {
-  /** @type {string} 模块 */
+  /** @type {string} 模块名称 */
   m = ''
 
-  /** @type {string} 函数 */
-  fn = ''
+  /** @type {string} 函数名称 */
+  fnName = ''
 
   /**
-   * @param {string} m 模块
+   * @param {string} [m=''] 模块
+   * @param {string} [fnName=''] 函数
    */
-  constructor(m) {
+  constructor(m = '', fnName = '') {
     this.m = m;
+    this.fnName = fnName;
   }
 
   /**
-   * get log desc
-   * 描述字符串后置调用，前置显示
-   * @param {*[]} args
-   * @returns {string}
+   * 格式化参数：提取提示符，构建前缀，将对象后置
+   * 格式要求：[模块名称:函数名称]提示符: {对象}
+   * @param {any[]} args
+   * @returns {any[]} 返回处理后传递给 console 的参数数组
    */
-  getDesc(args) {
+  formatArgs(args) {
     let R = '';
+    const _ = this;
     try {
-      const _ = this;
-      const { m } = _;
-      let fn = '',
-        desc = '';
-
-      if (args.length > 1) {
-        const last = args.at(-1);
-        if (typeof last === 'object') {
-          ;({ desc, fn } = last);
-        } else if (typeof last === 'string') desc = last;
-        if (desc || fn) {
-          fn = fn || _.fn;
-          _.fn = fn;
-          args.pop();
-        }
+      const msgs = [];
+      const objs = [];
+
+      // 1. 将字符串(提示符)和非字符串(对象/数值等)分开
+      for (const arg of args) {
+        if (typeof arg === 'string') msgs.push(arg);
+        else objs.push(arg);
       }
-      fn = fn || _.fn;
-      if (m) desc = `${desc}[${m}${fn ? ':' + fn : ''}]`; // eslint-disable-line
-      R = desc;
+
+      let prefix = '';
+
+      // 2. 添加模块与函数前缀
+      if (_.m) prefix = `[${_.m}${_.fnName ? ':' + _.fnName : ''}]`;
+      else if (_.fnName) prefix = `[:${_.fnName}]`;
+
+      // 3. 拼接提示符
+      const msg = msgs.join(' ');
+      if (msg) prefix += msg;
+
+      R = [];
+      if (prefix) R.push(prefix);
+      R.push(...objs);
     } catch (e) {
-      console.error(`getDesc exp:${e.message}`);
+      console.error(`formatArgs exp:${e.message}`);
     }
 
     return R
   }
 
-  /** @param {...any} args - params */
+  /** @param {...any} args */
   log(...args) {
-    const _ = this;
-    const last = args.at(-1);
-    // clear fn
-    if (args.length === 1 && typeof last === 'object' && last.fn) _.fn = '';
-    else {
-      const desc = _.getDesc(args);
-      console.log(desc, ...args);
-    }
+    // 生产环境安全剔除 (需 Rspack DefinePlugin 注入 __DEV__)
+    if (isDev) console.log(...this.formatArgs(args));
   }
 
-  /** @param {...any} args - params */
+  /** @param {...any} args */
   debug(...args) {
-    const _ = this;
-    const desc = _.getDesc(args);
-    if (desc) console.log(desc, ...args);
-    else console.log(...args);
+    if (isDev) console.debug(...this.formatArgs(args));
   }
 
-  /** @param {...any} args - params */
+  /** @param {...any} args */
   info(...args) {
-    const _ = this;
-    const desc = _.getDesc(args);
-    if (desc) console.info(desc, ...args);
-    else console.log(...args);
+    if (isDev) console.info(...this.formatArgs(args));
   }
 
-  /** @param {...any} args - params */
+  /** @param {...any} args */
   warn(...args) {
-    const _ = this;
-    const { desc, arg } = _.getDesc(args);
-    if (desc) console.warn(desc, ...arg);
-    else console.log(...args);
+    if (isDev) console.warn(...this.formatArgs(args));
   }
 
-  /** @param {...any} args - params */
+  /** @param {...any} args */
   trace(...args) {
-    const _ = this;
-    const { desc, arg } = _.getDesc(args);
-    if (desc) console.trace(desc, ...arg);
-    else console.trace(...args);
+    if (isDev) console.trace(...this.formatArgs(args));
   }
 
-  /** @param {...any} args - params */
+  /** * error 会在生产环境保留
+   * @param {...any} args
+   */
   error(...args) {
-    const _ = this;
-    const desc = _.getDesc(args);
-    if (desc) console.error(desc, ...args);
-    else console.log(...args);
+    console.error(...this.formatArgs(args));
   }
 
   /**
-   * 用于 catch(e) log.err(e)
-   * @param {...any} args - params */
+   * 用于 catch(e) log.err(e) 或 log.err("提示符", e) 或 log.err(e, "提示符")
+   * 自动对齐前缀 [模块:函数] 提示符: Error对象，并保留堆栈
+   * @param {...any} args
+   */
   err(...args) {
-    const _ = this;
-    const first = args?.[0];
-    if (
-      first instanceof Error ||
-      (first && first.message && first.cause && first.stack)
-    )
-      args[0] = { exp: args[0].message };
-    _.error(...args);
+    // 生产环境安全输出，不会被 Tree-shaking 摇掉
+    // formatArgs 会自动分离字符串与 Error 对象，并补全冒号
+    const formattedArgs = this.formatArgs(args);
+
+    // 原生打印，保持 stack trace 可点击跳转！
+    console.error(...formattedArgs);
   }
-}
 
-function getDesc(args) {
-  let desc = '';
-  const last = args.at(-1);
-  if (typeof last === 'string') {
-    desc = last;
-    args.pop();
+  /**
+   * 派生函数级别日志实例 (完美对齐后端 log.fn)
+   * @param {string} name 函数名称
+   * @returns {ScopedLogger}
+   */
+  fn(name) {
+    const scopedLog = new Log(this.m, name);
+
+    /** @type {any} */
+    const R = (...args) => scopedLog.log(...args);
+
+    R.debug = scopedLog.debug.bind(scopedLog);
+    R.info = scopedLog.info.bind(scopedLog);
+    R.warn = scopedLog.warn.bind(scopedLog);
+    R.trace = scopedLog.trace.bind(scopedLog);
+    R.error = scopedLog.error.bind(scopedLog);
+    R.err = scopedLog.err.bind(scopedLog);
+
+    return /** @type {ScopedLogger} */ (R)
   }
-  return desc
 }
 
+// 实例化唯一的全局日志单例
+const _log = new Log();
+
 /**
  * 标准日志输出或构建模块日志类实例，用于模块中带[m:xxx]标记日志输出
- * 启用 {f:fn} 标记时，需在函数尾部清除f（log({f:''})），否则会溢出到其他函数
+ * 传入 { m: '模块名' } 构建实例，或直接传入参数输出全局日志
  * @param {...any} args - params
  * returns {*}
  */
 function log(...args) {
   const last = args.at(-1);
 
-  // 全局日志
-  if (args.length !== 1 || !last?.m) {
-    const desc = getDesc(args);
-    desc ? console.log(desc, ...args) : console.log(...args);
-    return
-  }
-
-  // 唯一 m 属性，则构造新的 log 实例，这种写法，能被jsDoc识别子属性
-  const lg = new Log(last?.m);
-  /** @param {*} args2 */
-  const R = (...args2) => lg.log(...args2);
-  R.debug = lg.debug.bind(lg);
-  R.info = lg.info.bind(lg);
-  R.warn = lg.warn.bind(lg);
-  R.info = lg.info.bind(lg);
-  R.trace = lg.trace.bind(lg);
-  R.error = lg.error.bind(lg);
-  R.err = lg.err.bind(lg);
-
-  return R
-}
+  // 1. 如果只有一个参数且带 m 属性，说明是构造 Logger 实例 (如: const log = Log({m: 'User'}))
+  if (args.length === 1 && typeof last === 'object' && last !== null && 'm' in last) {
+    const lg = new Log(last.m);
 
-/**
- * 用于 catch(e) log.err(e)
- * @param {...any} args - params */
-log.err = (...args) => {
-  const desc = getDesc(args);
-  const first = args?.[0];
-  if (
-    first instanceof Error ||
-    (first && first.message && first.cause && first.stack)
-  )
-    args[0] = { exp: args[0].message };
-  desc ? console.error(desc, ...args) : console.error(...args);
-};
+    /** @type {any} */
+    const R = (...args2) => lg.log(...args2);
 
-/**
- * @param {...any} args - params */
-log.error = (...args) => {
-  const desc = getDesc(args);
-  desc ? console.error(desc, ...args) : console.error(...args);
-};
-
-/**
- * @param {...any} args - params */
-log.warn = (...args) => {
-  const desc = getDesc(args);
-  desc ? console.warn(desc, ...args) : console.warn(...args);
-};
+    R.log = lg.log.bind(lg);
+    R.debug = lg.debug.bind(lg);
+    R.info = lg.info.bind(lg);
+    R.warn = lg.warn.bind(lg);
+    R.trace = lg.trace.bind(lg);
+    R.error = lg.error.bind(lg);
+    R.err = lg.err.bind(lg);
+    R.fn = lg.fn.bind(lg); // 暴露派生函数作用域方法
 
-/**
- * @param {...any} args - params */
-log.info = (...args) => {
-  const desc = getDesc(args);
-  desc ? console.info(desc, ...args) : console.info(...args);
-};
+    return /** @type {LoggerFn} */ (R)
+  }
 
-/**
- * @param {...any} args - params */
-log.debug = (...args) => {
-  const desc = getDesc(args);
-  desc ? console.log(desc, ...args) : console.log(...args);
-};
+  // 2. 否则作为全局普通日志直接输出
+  _log.log(...args);
+}
 
-/**
- * @param {...any} args - params */
-log.trace = (...args) => {
-  const desc = getDesc(args);
-  desc ? console.trace(desc, ...args) : console.trace(...args);
-};
+// 绑定全局快捷方法，方便直接调用 log.err(e) 等
+log.err = _log.err.bind(_log);
+log.error = _log.error.bind(_log);
+log.warn = _log.warn.bind(_log);
+log.info = _log.info.bind(_log);
+log.debug = _log.debug.bind(_log);
+log.trace = _log.trace.bind(_log);
 
 /**
  * 所有页面从该类继承，并必须实现 load 事件！
@@ -2323,7 +2289,6 @@ log.trace = (...args) => {
  *
  */
 
-
 class Page extends Event {
   constructor(app, name, title, style) {
     super(null, [app]);

package/dist/jsx-runtime.js

@@ -1,5 +1,5 @@
 /*!
-  * wia core v1.2.3
+  * wia core v2.1.0
   * (c) 2015-2026 Sibyl Yu and contributors
   * Released under the MIT License.
   */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiajs/core",
-  "version": "1.2.3",
+  "version": "2.1.0",
   "description": "wia app core package",
   "keywords": [
     "core",

package/util/log.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 模块日志选项
+ */
+export interface LogOptions {
+  /** 模块名称 */
+  m: string
+}
+
+/**
+ * 派生函数级别的日志实例（支持直接作为函数调用，或调用内部方法）
+ */
+export interface ScopedLogger {
+  (...args: any[]): void
+  debug(...args: any[]): void
+  info(...args: any[]): void
+  warn(...args: any[]): void
+  error(...args: any[]): void
+  err(...args: any[]): void
+  trace(...args: any[]): void
+}
+
+/**
+ * 模块级别的日志实例（带有派生子函数 .fn 的能力）
+ */
+export interface LoggerFn {
+  (...args: any[]): void
+  log(...args: any[]): void
+  debug(...args: any[]): void
+  info(...args: any[]): void
+  warn(...args: any[]): void
+  error(...args: any[]): void
+  err(...args: any[]): void
+  trace(...args: any[]): void
+  /**
+   * 派生函数级别日志实例 (完美对齐后端 log.fn)
+   * @param name 函数名称
+   */
+  fn(name: string): ScopedLogger
+}
+
+/**
+ * 前端日志输出核心类
+ * 自动识别并重排提示符与对象，保持前后端一致性
+ */
+export class Log {
+  /** 模块名称 */
+  m: string
+  /** 函数名称 */
+  fnName: string
+
+  constructor(m?: string, fnName?: string)
+
+  /**
+   * 格式化参数：提取提示符，构建前缀，将对象后置
+   * 格式要求：[模块名称:函数名称]提示符: {对象}
+   * @param args
+   * @returns 返回处理后传递给 console 的参数数组
+   */
+  formatArgs(args: any[]): any[]
+
+  log(...args: any[]): void
+  debug(...args: any[]): void
+  info(...args: any[]): void
+  warn(...args: any[]): void
+  trace(...args: any[]): void
+
+  /**
+   * error 会在生产环境保留
+   */
+  error(...args: any[]): void
+
+  /**
+   * 用于 catch(e) log.err(e) 或 log.err("提示符", e) 或 log.err(e, "提示符")
+   * 自动对齐前缀 [模块:函数] 提示符: Error对象，并保留堆栈
+   */
+  err(...args: any[]): void
+
+  /**
+   * 派生函数级别日志实例
+   * @param name 函数名称
+   */
+  fn(name: string): ScopedLogger
+}
+
+/**
+ * 全局的 log 实例接口
+ * 实现了函数重载，支持构造日志模块对象，或是直接调用
+ */
+export interface GlobalLogger {
+  /**
+   * 构建模块日志类实例
+   * @example const uploaderLog = log({ m: 'uploader' })
+   */
+  (opt: LogOptions): LoggerFn
+
+  /**
+   * 标准日志输出 (无模块前缀)
+   * @example log('普通提示', { data: 1 })
+   */
+  (...args: any[]): void
+
+  err(...args: any[]): void
+  error(...args: any[]): void
+  warn(...args: any[]): void
+  info(...args: any[]): void
+  debug(...args: any[]): void
+  trace(...args: any[]): void
+}
+
+/**
+ * 标准日志输出或构建模块日志类实例
+ */
+export const log: GlobalLogger

package/util/log.js

@@ -0,0 +1,189 @@
+/**
+ * @typedef {Object} LogOptions
+ * @property {string} m - 模块名称
+ */
+
+/**
+ * @typedef {((...args: any[]) => void) & { debug: (...args: any[])=>void, info: (...args: any[])=>void, warn: (...args: any[])=>void, error: (...args: any[])=>void, err: (...args: any[])=>void }} ScopedLogger
+ */
+
+/**
+ * @typedef {((...args: any[]) => void) & { log: (...args: any[])=>void, debug: (...args: any[])=>void, info: (...args: any[])=>void, warn: (...args: any[])=>void, error: (...args: any[])=>void, err: (...args: any[])=>void, fn: (name: string) => ScopedLogger }} LoggerFn
+ */
+
+// 1. 安全地获取开发环境状态（兼容打包工具、浏览器和 Node.js）
+// 如果 Rspack 注入了 __DEV__，就用注入的值；如果是在 Node.js 下，就回退读取 process.env.NODE_ENV
+const isDev = typeof __DEV__ !== 'undefined' ? __DEV__ : process.env.NODE_ENV !== 'production'
+
+/**
+ * 前端日志输出，封装 console 日志，简化代码
+ * 自动识别并重排提示符与对象，保持前后端一致性
+ */
+class Log {
+  /** @type {string} 模块名称 */
+  m = ''
+
+  /** @type {string} 函数名称 */
+  fnName = ''
+
+  /**
+   * @param {string} [m=''] 模块
+   * @param {string} [fnName=''] 函数
+   */
+  constructor(m = '', fnName = '') {
+    this.m = m
+    this.fnName = fnName
+  }
+
+  /**
+   * 格式化参数：提取提示符，构建前缀，将对象后置
+   * 格式要求：[模块名称:函数名称]提示符: {对象}
+   * @param {any[]} args
+   * @returns {any[]} 返回处理后传递给 console 的参数数组
+   */
+  formatArgs(args) {
+    let R = ''
+    const _ = this
+    try {
+      const msgs = []
+      const objs = []
+
+      // 1. 将字符串(提示符)和非字符串(对象/数值等)分开
+      for (const arg of args) {
+        if (typeof arg === 'string') msgs.push(arg)
+        else objs.push(arg)
+      }
+
+      let prefix = ''
+
+      // 2. 添加模块与函数前缀
+      if (_.m) prefix = `[${_.m}${_.fnName ? ':' + _.fnName : ''}]`
+      else if (_.fnName) prefix = `[:${_.fnName}]`
+
+      // 3. 拼接提示符
+      const msg = msgs.join(' ')
+      if (msg) prefix += msg
+
+      R = []
+      if (prefix) R.push(prefix)
+      R.push(...objs)
+    } catch (e) {
+      console.error(`formatArgs exp:${e.message}`)
+    }
+
+    return R
+  }
+
+  /** @param {...any} args */
+  log(...args) {
+    // 生产环境安全剔除 (需 Rspack DefinePlugin 注入 __DEV__)
+    if (isDev) console.log(...this.formatArgs(args))
+  }
+
+  /** @param {...any} args */
+  debug(...args) {
+    if (isDev) console.debug(...this.formatArgs(args))
+  }
+
+  /** @param {...any} args */
+  info(...args) {
+    if (isDev) console.info(...this.formatArgs(args))
+  }
+
+  /** @param {...any} args */
+  warn(...args) {
+    if (isDev) console.warn(...this.formatArgs(args))
+  }
+
+  /** @param {...any} args */
+  trace(...args) {
+    if (isDev) console.trace(...this.formatArgs(args))
+  }
+
+  /** * error 会在生产环境保留
+   * @param {...any} args
+   */
+  error(...args) {
+    console.error(...this.formatArgs(args))
+  }
+
+  /**
+   * 用于 catch(e) log.err(e) 或 log.err("提示符", e) 或 log.err(e, "提示符")
+   * 自动对齐前缀 [模块:函数] 提示符: Error对象，并保留堆栈
+   * @param {...any} args
+   */
+  err(...args) {
+    // 生产环境安全输出，不会被 Tree-shaking 摇掉
+    // formatArgs 会自动分离字符串与 Error 对象，并补全冒号
+    const formattedArgs = this.formatArgs(args)
+
+    // 原生打印，保持 stack trace 可点击跳转！
+    console.error(...formattedArgs)
+  }
+
+  /**
+   * 派生函数级别日志实例 (完美对齐后端 log.fn)
+   * @param {string} name 函数名称
+   * @returns {ScopedLogger}
+   */
+  fn(name) {
+    const scopedLog = new Log(this.m, name)
+
+    /** @type {any} */
+    const R = (...args) => scopedLog.log(...args)
+
+    R.debug = scopedLog.debug.bind(scopedLog)
+    R.info = scopedLog.info.bind(scopedLog)
+    R.warn = scopedLog.warn.bind(scopedLog)
+    R.trace = scopedLog.trace.bind(scopedLog)
+    R.error = scopedLog.error.bind(scopedLog)
+    R.err = scopedLog.err.bind(scopedLog)
+
+    return /** @type {ScopedLogger} */ (R)
+  }
+}
+
+// 实例化唯一的全局日志单例
+const _log = new Log()
+
+/**
+ * 标准日志输出或构建模块日志类实例，用于模块中带[m:xxx]标记日志输出
+ * 传入 { m: '模块名' } 构建实例，或直接传入参数输出全局日志
+ * @param {...any} args - params
+ * returns {*}
+ */
+function log(...args) {
+  const last = args.at(-1)
+
+  // 1. 如果只有一个参数且带 m 属性，说明是构造 Logger 实例 (如: const log = Log({m: 'User'}))
+  if (args.length === 1 && typeof last === 'object' && last !== null && 'm' in last) {
+    const lg = new Log(last.m)
+
+    /** @type {any} */
+    const R = (...args2) => lg.log(...args2)
+
+    R.log = lg.log.bind(lg)
+    R.debug = lg.debug.bind(lg)
+    R.info = lg.info.bind(lg)
+    R.warn = lg.warn.bind(lg)
+    R.trace = lg.trace.bind(lg)
+    R.error = lg.error.bind(lg)
+    R.err = lg.err.bind(lg)
+    R.fn = lg.fn.bind(lg) // 暴露派生函数作用域方法
+
+    return /** @type {LoggerFn} */ (R)
+  }
+
+  // 2. 否则作为全局普通日志直接输出
+  _log.log(...args)
+}
+
+// 绑定全局快捷方法，方便直接调用 log.err(e) 等
+log.err = _log.err.bind(_log)
+log.error = _log.error.bind(_log)
+log.warn = _log.warn.bind(_log)
+log.info = _log.info.bind(_log)
+log.debug = _log.debug.bind(_log)
+log.trace = _log.trace.bind(_log)
+
+export {log, Log}