@wiajs/core 1.2.2 → 2.1.0

package/package.json

@@ -1,52 +1,52 @@
 {
   "name": "@wiajs/core",
-  "version": "1.2.2",
+  "version": "2.1.0",
   "description": "wia app core package",
+  "keywords": [
+    "core",
+    "wia"
+  ],
+  "homepage": "https://www.wia.pub/core",
+  "bugs": {
+    "url": "https://github.com/wiajs/core/issues"
+  },
+  "license": "ELv2",
+  "author": {
+    "name": "Sibyl Yu",
+    "email": "sibyl@wia.pub"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wiajs/wia.git"
+  },
   "main": "./dist/core.cjs",
   "module": "./dist/core.mjs",
   "types": "./types/core.d.ts",
-	"exports": {
- 		".": {
+  "exports": {
+    ".": {
       "types": "./types/core.d.ts",
       "require": "./dist/core.cjs",
       "import": "./dist/core.mjs",
       "default": "./dist/core.mjs"
     },
-    "./jsx-runtime":  "./dist/jsx-runtime.js",
-    "./jsx-dev-runtime": "./dist/jsx-runtime.js",   
+    "./jsx-runtime": "./dist/jsx-runtime.js",
+    "./jsx-dev-runtime": "./dist/jsx-runtime.js",
     "./util/*": [
       "./util/*.js",
       "./util/*.d.ts"
-    ]		
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "build": "cross-env NODE_ENV=production gulp build",
     "build-dev": "cross-env NODE_ENV=development gulp build",
     "dev": "cross-env NODE_ENV=development gulp cjs",
-    "dev:umd": "cross-env NODE_ENV=development gulp umd",
     "dev:esm": "cross-env NODE_ENV=development gulp esm",
+    "dev:umd": "cross-env NODE_ENV=development gulp umd",
     "release": "bash release.sh"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wiajs/wia.git"
-  },
-  "keywords": [
-    "wia",
-    "core"
-  ],
-  "author": {
-    "name": "Sibyl Yu",
-    "email": "sibyl@wia.pub"
-  },
-  "license": "ELv2",
-  "bugs": {
-    "url": "https://github.com/wiajs/core/issues"
-  },
-  "homepage": "https://www.wia.pub/core",
-  "publishConfig": {
-    "access": "public"
-  },
   "devDependencies": {
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-commonjs": "^25.0.1",

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}