@aithe/aithe-ui 26.2.2 → 26.3.1

package/dist/core/logger/LoggerCore.js

@@ -0,0 +1,626 @@
+import { LogLevel, LOG_LEVEL_LABEL, DEFAULT_LOG_CONFIG, } from './types';
+/**
+ * Map native console methods to the appropriate log level.
+ * console.log → INFO is more conventional than DEBUG.
+ */
+const CONSOLE_LEVEL_MAP = {
+    log: LogLevel.INFO,
+    info: LogLevel.INFO,
+    warn: LogLevel.WARN,
+    error: LogLevel.ERROR,
+};
+/** Auto-incrementing counter for unique entry IDs. */
+let idCounter = 0;
+function generateId() {
+    return `log_${Date.now()}_${++idCounter}`;
+}
+/**
+ * Convert the first log argument to a string message.
+ * 将日志的第一个参数转为字符串消息。
+ */
+function firstArgToString(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (value instanceof Error)
+        return value.message;
+    return safeToString(value);
+}
+/**
+ * Safely convert any value to a string, protecting against circular refs.
+ * 安全地将任意值转为字符串，防止循环引用。
+ */
+function safeToString(value) {
+    try {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+            return String(value);
+        }
+        if (value instanceof Error)
+            return value.message;
+        return JSON.stringify(value, safeReplacer());
+    }
+    catch {
+        return '[Unserializable]';
+    }
+}
+/**
+ * JSON.stringify replacer that guards against circular references and
+ * non-serializable values. 防止循环引用和不可序列化值的 JSON.stringify 替换函数。
+ */
+function safeReplacer() {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+        }
+        if (typeof value === 'function')
+            return '[Function]';
+        if (typeof value === 'symbol')
+            return value.toString();
+        if (typeof value === 'bigint')
+            return `BigInt(${value})`;
+        if (value === undefined)
+            return '[Undefined]';
+        return value;
+    };
+}
+/**
+ * Safely serialize an unknown value to a JSON-compatible representation.
+ * 将未知值安全序列化为 JSON 兼容的表示。
+ */
+function safeSerialize(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    try {
+        return JSON.parse(JSON.stringify(value, safeReplacer()));
+    }
+    catch {
+        return safeToString(value);
+    }
+}
+/**
+ * Extract a stack trace if available.
+ * 提取可用的调用栈。
+ */
+function extractStack(data) {
+    const err = data.find((a) => a instanceof Error);
+    if (err?.stack)
+        return err.stack;
+    try {
+        return new Error('LoggerCore: stack capture').stack?.replace(/^Error: LoggerCore: stack capture\n/, '') ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Browser env helpers                                                 */
+/* ------------------------------------------------------------------ */
+function currentUrl() {
+    try {
+        return typeof location === 'undefined' ? '' : location.href;
+    }
+    catch {
+        return '';
+    }
+}
+function userAgent() {
+    try {
+        return typeof navigator === 'undefined' ? '' : navigator.userAgent;
+    }
+    catch {
+        return '';
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Entry factory                                                       */
+/* ------------------------------------------------------------------ */
+function createEntry(level, message, data, tags) {
+    return {
+        id: generateId(),
+        timestamp: Date.now(),
+        level,
+        levelLabel: LOG_LEVEL_LABEL[level] ?? 'UNKNOWN',
+        message: message || (LOG_LEVEL_LABEL[level] ?? ''),
+        data,
+        url: currentUrl(),
+        ua: userAgent(),
+        stack: level >= LogLevel.ERROR ? extractStack(data) : undefined,
+        tags,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  LoggerCore                                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Core logger that intercepts `console` calls, captures global errors,
+ * aithe-* component events (via `emitAitheEvent`), and optionally reports
+ * to a remote endpoint.
+ * Hijacks console and starts error capture immediately on construction.
+ *
+ * 核心日志器：拦截 console 调用、捕获全局错误、aithe-* 组件事件（通过 `emitAitheEvent`），并可远程上报。
+ * 构造时即劫持 console 并开始错误捕获。
+ *
+ * @example
+ * ```ts
+ * import logger from '../logger';
+ * logger.setMinLevel(LogLevel.WARN);
+ * logger.setReporter({ url: '/log', levelThreshold: LogLevel.ERROR });
+ * logger.info('Component mounted');          // filtered by minLevel
+ * logger.error('Failed to load', new Error()); // stored & reported
+ * ```
+ */
+export class LoggerCore {
+    /* ---- Construction ---- */
+    /**
+     * Create a logger instance. Normally import the default singleton from `@core/logger`.
+     * 创建日志器实例。通常从 `@core/logger` 导入默认单例即可。
+     *
+     * @example
+     * ```ts
+     * // Use the default singleton. 使用默认单例。
+     * import logger from '../logger';
+     *
+     * // Or create an isolated instance for testing. 或为测试创建独立实例。
+     * const testLogger = new LoggerCore({ minLevel: LogLevel.ERROR });
+     * ```
+     */
+    constructor(config) {
+        /* ---- Private state ---- */
+        this._entries = [];
+        this._listeners = new Set();
+        this._clearListeners = new Set();
+        this._originalConsole = null;
+        this._hijacked = false;
+        /* Remote reporting */
+        this._reportBuffer = [];
+        this._reportTimer = null;
+        /* Global error capture */
+        this._globalErrorHandler = null;
+        this._rejectionHandler = null;
+        this._config = { ...DEFAULT_LOG_CONFIG, ...config };
+        this.hijack();
+        this.startGlobalErrorCapture();
+    }
+    /* ---- Public accessors ---- */
+    /** All recorded entries. 所有已记录的日志条目。 */
+    get entries() {
+        return this._entries;
+    }
+    /** Whether console methods are currently hijacked. 当前是否已劫持 console 方法。 */
+    get isHijacked() {
+        return this._hijacked;
+    }
+    /** Current configuration (read-only reference). 当前配置（只读引用）。 */
+    get config() {
+        return this._config;
+    }
+    /* ---- Configuration ---- */
+    /**
+     * Enable logging. `addEntry()` will start recording and notifying listeners.
+     * 启用日志记录。`addEntry()` 将开始记录并通知监听器。
+     */
+    enable() {
+        this._config.enabled = true;
+    }
+    /**
+     * Disable logging. `addEntry()` returns early — console output still works.
+     * Use this to eliminate per-call overhead in production / high-frequency loops.
+     * 禁用日志记录。`addEntry()` 直接返回 — console 输出不受影响。
+     * 用于生产环境或高频循环中消除每次调用的开销。
+     */
+    disable() {
+        this._config.enabled = false;
+    }
+    /** Whether logging is currently enabled. 当前是否已启用日志记录。 */
+    get isEnabled() {
+        return this._config.enabled;
+    }
+    /**
+     * Apply partial configuration overrides. Only provided fields are updated.
+     * 应用部分配置覆盖。仅更新提供的字段。
+     *
+     * @param config - Partial configuration overrides. 配置覆盖项。
+     */
+    applyConfig(config) {
+        if (config.enabled !== undefined) {
+            this._config.enabled = config.enabled;
+        }
+        if (config.reporter !== undefined) {
+            this._config.reporter = config.reporter;
+        }
+        if (config.minLevel !== undefined) {
+            this._config.minLevel = config.minLevel;
+        }
+        if (config.maxEntries !== undefined) {
+            this.setMaxEntries(config.maxEntries);
+        }
+    }
+    /**
+     * Update the minimum log level. Entries below this level will not be stored.
+     * 更新最低日志级别。低于此级别的条目将不会被存储。
+     */
+    setMinLevel(level) {
+        this._config.minLevel = level;
+    }
+    /**
+     * Set the maximum number of entries retained in memory.
+     * Existing entries will be trimmed if necessary.
+     * 设置内存中保留的最大条目数。如有必要，现有条目将被修剪。
+     */
+    setMaxEntries(max) {
+        this._config.maxEntries = max;
+        if (this._entries.length > max) {
+            this._entries = this._entries.slice(-max);
+        }
+    }
+    /**
+     * Configure or remove the remote reporter.
+     * 配置或移除远程上报器。
+     *
+     * @param config - Reporter config, or `undefined` to disable reporting. 上报配置，传 undefined 禁用上报。
+     */
+    setReporter(config) {
+        if (config === undefined) {
+            delete this._config.reporter;
+        }
+        else {
+            this._config.reporter = config;
+        }
+    }
+    /**
+     * Restore original console methods and stop all listeners.
+     * 恢复原始 console 方法并停止所有监听器。
+     */
+    restore() {
+        if (!this._hijacked || !this._originalConsole)
+            return;
+        // eslint-disable-next-line no-console
+        console.log = this._originalConsole.log;
+        // eslint-disable-next-line no-console
+        console.info = this._originalConsole.info;
+        // eslint-disable-next-line no-console
+        console.warn = this._originalConsole.warn;
+        // eslint-disable-next-line no-console
+        console.error = this._originalConsole.error;
+        this._originalConsole = null;
+        this._hijacked = false;
+        this.stopGlobalErrorCapture();
+    }
+    /**
+     * Fully destroy the logger: restore console, flush reports, clear state.
+     *
+     * 彻底销毁日志器：恢复 console、刷新上报、清空状态。
+     */
+    destroy() {
+        this.restore();
+        this._flushReport();
+        this._listeners.clear();
+        this._clearListeners.clear();
+        this._entries = [];
+    }
+    /* ---- Console hijacking ---- */
+    /**
+     * Intercept native console methods. 劫持原生 console 方法。
+     */
+    hijack() {
+        if (this._hijacked)
+            return;
+        this._originalConsole = {
+            log: console.log.bind(console), // eslint-disable-line no-console
+            info: console.info.bind(console), // eslint-disable-line no-console
+            warn: console.warn.bind(console), // eslint-disable-line no-console
+            error: console.error.bind(console), // eslint-disable-line no-console
+        };
+        for (const method of ['log', 'info', 'warn', 'error']) {
+            const original = this._originalConsole[method];
+            const level = CONSOLE_LEVEL_MAP[method];
+            this._overrideConsoleMethod(method, original, level);
+        }
+        this._hijacked = true;
+    }
+    /**
+     * Override a single console method to forward calls to the logger.
+     * 覆盖单个 console 方法，将调用转发到日志器。
+     */
+    _overrideConsoleMethod(method, original, level) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        console[method] = (...args) => {
+            original(...args);
+            this.addEntry(level, args);
+        };
+    }
+    /* ---- Log entry management ---- */
+    /**
+     * Add a log entry programmatically. Used internally and exposed for direct calls.
+     * 以编程方式添加日志条目。内部使用，同时暴露供直接调用。
+     *
+     * @param level - Severity level. 严重级别。
+     * @param args  - Arbitrary arguments. 任意参数。
+     * @param tags  - Optional context tags. 可选的上下文标签。
+     */
+    addEntry(level, args, tags) {
+        // args[0] → message, args[1..] → data
+        const message = args.length > 0 ? firstArgToString(args[0]) : '';
+        const data = args.slice(1);
+        // Bail early when globally disabled — the cheapest path possible.
+        if (!this._config.enabled) {
+            return {
+                id: generateId(),
+                timestamp: Date.now(),
+                level,
+                levelLabel: LOG_LEVEL_LABEL[level] ?? 'UNKNOWN',
+                message,
+                data,
+                url: '',
+                ua: '',
+            };
+        }
+        // Respect minLevel filter
+        if (level < this._config.minLevel) {
+            return createEntry(level, message, data, tags);
+        }
+        const entry = createEntry(level, message, data, tags);
+        this._entries.push(entry);
+        // Trim to max capacity
+        if (this._entries.length > this._config.maxEntries) {
+            this._entries = this._entries.slice(-this._config.maxEntries);
+        }
+        this._notifyListeners(entry);
+        this._enqueueReport(entry);
+        return entry;
+    }
+    /**
+     * Convenience: log at a given level. 便捷方法：以指定级别记录日志。
+     */
+    log(level, ...args) {
+        return this.addEntry(level, args);
+    }
+    /** Log at DEBUG level. 以 DEBUG 级别记录。 */
+    debug(...args) {
+        return this.log(LogLevel.DEBUG, ...args);
+    }
+    /** Log at INFO level. 以 INFO 级别记录。 */
+    info(...args) {
+        return this.log(LogLevel.INFO, ...args);
+    }
+    /** Log at WARN level. 以 WARN 级别记录。 */
+    warn(...args) {
+        return this.log(LogLevel.WARN, ...args);
+    }
+    /** Log at ERROR level. 以 ERROR 级别记录。 */
+    error(...args) {
+        return this.log(LogLevel.ERROR, ...args);
+    }
+    /** Log at FATAL level. 以 FATAL 级别记录。 */
+    fatal(...args) {
+        return this.log(LogLevel.FATAL, ...args);
+    }
+    /**
+     * Retrieve entries filtered by minimum level. 按最低级别过滤获取日志条目。
+     *
+     * @param minLevel - Minimum log level threshold. 最低日志级别阈值。
+     * @returns Filtered list of entries. 过滤后的条目列表。
+     */
+    getEntries(minLevel) {
+        if (minLevel === undefined)
+            return this._entries;
+        return this._entries.filter((e) => e.level >= minLevel);
+    }
+    /**
+     * Clear all stored entries and notify clear listeners.
+     * 清空所有存储的条目并通知清空监听器。
+     */
+    clear() {
+        const snapshot = this._entries;
+        this._entries = [];
+        this._notifyClearListeners(snapshot);
+    }
+    /* ---- Subscription ---- */
+    /**
+     * Subscribe to new log entries. Returns an unsubscribe function.
+     * 订阅新日志条目。返回取消订阅函数。
+     *
+     * @param listener - Callback invoked on every new entry. 每条新日志时触发的回调。
+     * @returns Unsubscribe function. 取消订阅函数。
+     */
+    subscribe(listener) {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    }
+    /**
+     * Subscribe to log clear events. 订阅日志清空事件。
+     *
+     * @param listener - Callback invoked when entries are cleared. 条目清空时触发的回调。
+     * @returns Unsubscribe function. 取消订阅函数。
+     */
+    onClear(listener) {
+        this._clearListeners.add(listener);
+        return () => {
+            this._clearListeners.delete(listener);
+        };
+    }
+    _notifyListeners(entry) {
+        const entries = this._entries;
+        for (const listener of this._listeners) {
+            try {
+                listener(entry, entries);
+            }
+            catch {
+                // Swallow listener errors to prevent cascading failures.
+                // 吞没监听器错误以防止连锁故障。
+            }
+        }
+    }
+    _notifyClearListeners(entriesBeforeClear) {
+        for (const listener of this._clearListeners) {
+            try {
+                listener(entriesBeforeClear);
+            }
+            catch {
+                // Swallow
+            }
+        }
+    }
+    /* ---- Global error capture ---- */
+    /**
+     * Start capturing uncaught errors and unhandled promise rejections.
+     * 开始捕获未捕获的错误和未处理的 Promise 拒绝。
+     */
+    startGlobalErrorCapture() {
+        if (this._globalErrorHandler)
+            return;
+        this._globalErrorHandler = (ev) => {
+            this.addEntry(LogLevel.ERROR, [
+                `[Uncaught] ${ev.message}`,
+                {
+                    filename: ev.filename,
+                    lineno: ev.lineno,
+                    colno: ev.colno,
+                    error: ev.error,
+                },
+            ]);
+        };
+        this._rejectionHandler = (ev) => {
+            this.addEntry(LogLevel.ERROR, [`[UnhandledRejection] ${ev.reason}`, { reason: ev.reason }]);
+        };
+        globalThis.addEventListener('error', this._globalErrorHandler);
+        globalThis.addEventListener('unhandledrejection', this._rejectionHandler);
+    }
+    /**
+     * Stop global error listeners. 停止全局错误监听器。
+     */
+    stopGlobalErrorCapture() {
+        if (this._globalErrorHandler) {
+            globalThis.removeEventListener('error', this._globalErrorHandler);
+            this._globalErrorHandler = null;
+        }
+        if (this._rejectionHandler) {
+            globalThis.removeEventListener('unhandledrejection', this._rejectionHandler);
+            this._rejectionHandler = null;
+        }
+    }
+    /* ---- Remote reporting ---- */
+    _enqueueReport(entry) {
+        const reporter = this._config.reporter;
+        if (!reporter)
+            return;
+        if (entry.level < reporter.levelThreshold)
+            return;
+        this._reportBuffer.push(entry);
+        const batchSize = reporter.batchSize ?? 10;
+        if (this._reportBuffer.length >= batchSize) {
+            this._flushReport();
+            return;
+        }
+        if (!this._reportTimer) {
+            const debounceMs = reporter.debounceMs ?? 3000;
+            this._reportTimer = setTimeout(() => this._flushReport(), debounceMs);
+        }
+    }
+    _flushReport() {
+        if (this._reportTimer) {
+            clearTimeout(this._reportTimer);
+            this._reportTimer = null;
+        }
+        const reporter = this._config.reporter;
+        if (!reporter || this._reportBuffer.length === 0)
+            return;
+        const batch = this._reportBuffer.splice(0);
+        this._sendReport(batch, reporter);
+    }
+    _sendReport(batch, reporter) {
+        let payload = batch.map((e) => ({
+            id: e.id,
+            timestamp: e.timestamp,
+            level: e.levelLabel,
+            message: e.message,
+            url: e.url,
+            ua: e.ua,
+            stack: e.stack,
+            data: e.data.length === 1 ? safeSerialize(e.data[0]) : safeSerialize(e.data),
+            tags: e.tags,
+        }));
+        if (reporter.beforeSend) {
+            const result = reporter.beforeSend(payload);
+            if (result === false)
+                return;
+            if (Array.isArray(result))
+                payload = result;
+        }
+        try {
+            fetch(reporter.url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...reporter.headers,
+                },
+                body: JSON.stringify(payload),
+                keepalive: true,
+            }).catch(() => {
+                // Swallow network errors. 吞没网络错误。
+            });
+        }
+        catch {
+            // Swallow
+        }
+    }
+    /* ---- Utility: formatted console output ---- */
+    /**
+     * Pretty-print recent entries to the original console with colored level labels.
+     * 将最近的日志条目格式化输出到原始控制台，带彩色级别标签。
+     *
+     * @param max - Max entries to print (default: 50). 最大打印条目数（默认 50）。
+     */
+    print(max = 50) {
+        const original = this._originalConsole;
+        const out = original?.log ?? console.log; // eslint-disable-line no-console
+        const levelStyle = {
+            DEBUG: 'color: #8899aa',
+            INFO: 'color: #3399ee',
+            WARN: 'color: #ee9900; font-weight: bold',
+            ERROR: 'color: #ee3333; font-weight: bold',
+            FATAL: 'color: #ffffff; background: #ee3333; font-weight: bold',
+        };
+        const slice = this._entries.slice(-max);
+        for (const entry of slice) {
+            const label = entry.levelLabel;
+            const style = levelStyle[label] ?? '';
+            const time = new Date(entry.timestamp).toISOString();
+            out(`%c[${label}]%c ${time} %c${entry.message}`, style, '', 'color: inherit');
+        }
+    }
+    /**
+     * Export all entries as JSON-safe array. 将所有条目导出为 JSON 安全数组。
+     */
+    serialize() {
+        return this._entries.map((e) => ({
+            id: e.id,
+            timestamp: e.timestamp,
+            level: e.levelLabel,
+            message: e.message,
+            url: e.url,
+            ua: e.ua,
+            stack: e.stack,
+            data: safeSerialize(e.data),
+            tags: e.tags,
+        }));
+    }
+}

package/dist/core/logger/index.d.ts

@@ -0,0 +1,12 @@
+export { LoggerCore } from './LoggerCore';
+export { LogLevel, LOG_LEVEL_LABEL, DEFAULT_LOG_CONFIG } from './types';
+export type { LogEntry, LogListener, LogClearListener, LogConfig, LogReporterConfig, LogSerializedPayload, } from './types';
+import { LoggerCore } from './LoggerCore';
+/**
+ * Default singleton logger instance. Console hijacking and error capture start
+ * immediately on module load. Customise via `applyConfig()` / `setMinLevel()` etc.
+ * 默认单例日志器实例。模块加载时即开始劫持 console 与错误捕获。
+ * 通过 `applyConfig()` / `setMinLevel()` 等方法定制配置。
+ */
+export declare const logger: LoggerCore;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/logger/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACxE,YAAY,EACV,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,MAAM,YAAmB,CAAC"}

package/dist/core/logger/index.js

@@ -0,0 +1,10 @@
+export { LoggerCore } from './LoggerCore';
+export { LogLevel, LOG_LEVEL_LABEL, DEFAULT_LOG_CONFIG } from './types';
+import { LoggerCore } from './LoggerCore';
+/**
+ * Default singleton logger instance. Console hijacking and error capture start
+ * immediately on module load. Customise via `applyConfig()` / `setMinLevel()` etc.
+ * 默认单例日志器实例。模块加载时即开始劫持 console 与错误捕获。
+ * 通过 `applyConfig()` / `setMinLevel()` 等方法定制配置。
+ */
+export const logger = new LoggerCore();