@be-link/cls-logger 1.0.1-beta.17 → 1.0.1-beta.18

package/dist/web.js

@@ -201,6 +201,9 @@ class ClsLoggerCore {
         this.batchTimerDueAt = null;
         this.initTs = 0;
         this.startupDelayMs = 0;
+        this.useIdleCallback = false;
+        this.idleTimeout = 3000;
+        this.visibilityCleanup = null;
         // 参考文档：失败缓存 + 重试
         this.failedCacheKey = 'cls_failed_logs';
         this.failedCacheMax = 200;
@@ -270,6 +273,8 @@ class ClsLoggerCore {
         this.batchMaxSize = options.batch?.maxSize ?? this.batchMaxSize;
         this.batchIntervalMs = options.batch?.intervalMs ?? this.batchIntervalMs;
         this.startupDelayMs = options.batch?.startupDelayMs ?? this.startupDelayMs;
+        this.useIdleCallback = options.batch?.useIdleCallback ?? this.useIdleCallback;
+        this.idleTimeout = options.batch?.idleTimeout ?? this.idleTimeout;
         this.failedCacheKey = options.failedCacheKey ?? this.failedCacheKey;
         this.failedCacheMax = options.failedCacheMax ?? this.failedCacheMax;
         // 预热（避免首条日志触发 import/初始化开销）
@@ -279,6 +284,8 @@ class ClsLoggerCore {
         if (this.enabled) {
             // 启动时尝试发送失败缓存
             this.flushFailed();
+            // 添加页面可见性监听（确保页面关闭时数据不丢失）
+            this.setupVisibilityListener();
             // 初始化后立即启动请求监听
             this.startRequestMonitor(options.requestMonitor);
             // 初始化后立即启动错误监控/性能监控
@@ -315,6 +322,89 @@ class ClsLoggerCore {
             return auto;
         return undefined;
     }
+    /**
+     * 设置页面可见性监听
+     * - visibilitychange: 页面隐藏时使用 sendBeacon 发送队列
+     * - pagehide: 作为移动端 fallback
+     */
+    setupVisibilityListener() {
+        if (typeof document === 'undefined' || typeof window === 'undefined')
+            return;
+        // 避免重复监听
+        if (this.visibilityCleanup)
+            return;
+        const handleVisibilityChange = () => {
+            if (document.visibilityState === 'hidden') {
+                this.flushBatchSync();
+            }
+        };
+        const handlePageHide = () => {
+            this.flushBatchSync();
+        };
+        document.addEventListener('visibilitychange', handleVisibilityChange);
+        window.addEventListener('pagehide', handlePageHide);
+        this.visibilityCleanup = () => {
+            document.removeEventListener('visibilitychange', handleVisibilityChange);
+            window.removeEventListener('pagehide', handlePageHide);
+        };
+    }
+    /**
+     * 同步发送内存队列（使用 sendBeacon）
+     * - 用于页面关闭时确保数据发送
+     * - sendBeacon 不可用时降级为缓存到 localStorage
+     */
+    flushBatchSync() {
+        if (this.memoryQueue.length === 0)
+            return;
+        // 清除定时器
+        if (this.batchTimer) {
+            try {
+                if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
+                    cancelIdleCallback(this.batchTimer);
+                }
+                else {
+                    clearTimeout(this.batchTimer);
+                }
+            }
+            catch {
+                // ignore
+            }
+            this.batchTimer = null;
+        }
+        this.batchTimerDueAt = null;
+        const logs = [...this.memoryQueue];
+        this.memoryQueue = [];
+        // 优先使用 sendBeacon（页面关闭时可靠发送）
+        if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+            try {
+                const payload = this.buildSendBeaconPayload(logs);
+                const blob = new Blob([payload], { type: 'application/json' });
+                const url = `${this.endpoint}/structuredlog?topic_id=${this.topicId}`;
+                const success = navigator.sendBeacon(url, blob);
+                if (!success) {
+                    // sendBeacon 返回 false 时，降级缓存
+                    this.cacheFailedReportLogs(logs);
+                }
+            }
+            catch {
+                this.cacheFailedReportLogs(logs);
+            }
+        }
+        else {
+            // 不支持 sendBeacon，降级缓存到 localStorage
+            this.cacheFailedReportLogs(logs);
+        }
+    }
+    /**
+     * 构建 sendBeacon 的 payload
+     */
+    buildSendBeaconPayload(logs) {
+        const logList = logs.map((log) => this.buildReportFields(log));
+        return JSON.stringify({
+            source: this.source,
+            logs: logList,
+        });
+    }
     startRequestMonitor(requestMonitor) {
         if (this.requestMonitorStarted)
             return;
@@ -569,25 +659,55 @@ class ClsLoggerCore {
         const desiredDelay = Math.max(0, desiredDueAt - now);
         if (!this.batchTimer) {
             this.batchTimerDueAt = desiredDueAt;
-            this.batchTimer = setTimeout(() => {
-                void this.flushBatch();
-            }, desiredDelay);
+            this.scheduleFlush(desiredDelay);
             return;
         }
-        // 启动合并窗口内：如果当前 timer 会“更早”触发，则延后到窗口结束，尽量减少多次发送
+        // 启动合并窗口内：如果当前 timer 会"更早"触发，则延后到窗口结束，尽量减少多次发送
         if (this.batchTimerDueAt !== null && this.batchTimerDueAt < desiredDueAt) {
-            try {
-                clearTimeout(this.batchTimer);
-            }
-            catch {
-                // ignore
-            }
+            this.cancelScheduledFlush();
             this.batchTimerDueAt = desiredDueAt;
+            this.scheduleFlush(desiredDelay);
+        }
+    }
+    /**
+     * 调度批量发送
+     * - 支持 requestIdleCallback（浏览器空闲时执行）
+     * - 降级为 setTimeout
+     */
+    scheduleFlush(desiredDelay) {
+        if (this.useIdleCallback && typeof requestIdleCallback !== 'undefined') {
+            // 使用 requestIdleCallback，设置 timeout 保证最终执行
+            const idleId = requestIdleCallback(() => {
+                void this.flushBatch();
+            }, { timeout: Math.max(desiredDelay, this.idleTimeout) });
+            // 存储 idleId 以便清理（类型兼容处理）
+            this.batchTimer = idleId;
+        }
+        else {
             this.batchTimer = setTimeout(() => {
                 void this.flushBatch();
             }, desiredDelay);
         }
     }
+    /**
+     * 取消已调度的批量发送
+     */
+    cancelScheduledFlush() {
+        if (!this.batchTimer)
+            return;
+        try {
+            if (this.useIdleCallback && typeof cancelIdleCallback !== 'undefined') {
+                cancelIdleCallback(this.batchTimer);
+            }
+            else {
+                clearTimeout(this.batchTimer);
+            }
+        }
+        catch {
+            // ignore
+        }
+        this.batchTimer = null;
+    }
     getDesiredBatchFlushDueAt(nowTs) {
         const start = this.initTs || nowTs;
         const startupDelay = Number.isFinite(this.startupDelayMs) ? Math.max(0, this.startupDelayMs) : 0;
@@ -598,7 +718,7 @@ class ClsLoggerCore {
         }
         return nowTs + this.batchIntervalMs;
     }
-    info(message, data = {}) {
+    info(message, data = {}, options) {
         let msg = '';
         let extra = {};
         if (message instanceof Error) {
@@ -614,9 +734,18 @@ class ClsLoggerCore {
             extra = data;
         }
         const payload = normalizeFlatFields({ message: msg, ...extra }, 'info');
-        this.report({ type: 'info', data: payload, timestamp: Date.now() });
+        const log = { type: 'info', data: payload, timestamp: Date.now() };
+        // info 默认走批量队列，支持 immediate 选项立即发送
+        if (options?.immediate) {
+            void this.sendReportLogs([log]).catch(() => {
+                this.cacheFailedReportLogs([log]);
+            });
+        }
+        else {
+            this.report(log);
+        }
     }
-    warn(message, data = {}) {
+    warn(message, data = {}, options) {
         let msg = '';
         let extra = {};
         if (message instanceof Error) {
@@ -632,9 +761,18 @@ class ClsLoggerCore {
             extra = data;
         }
         const payload = normalizeFlatFields({ message: msg, ...extra }, 'warn');
-        this.report({ type: 'warn', data: payload, timestamp: Date.now() });
+        const log = { type: 'warn', data: payload, timestamp: Date.now() };
+        // warn 默认走批量队列，支持 immediate 选项立即发送
+        if (options?.immediate) {
+            void this.sendReportLogs([log]).catch(() => {
+                this.cacheFailedReportLogs([log]);
+            });
+        }
+        else {
+            this.report(log);
+        }
     }
-    error(message, data = {}) {
+    error(message, data = {}, options) {
         let msg = '';
         let extra = {};
         if (message instanceof Error) {
@@ -650,7 +788,17 @@ class ClsLoggerCore {
             extra = data;
         }
         const payload = normalizeFlatFields({ message: msg, ...extra }, 'error');
-        this.report({ type: 'error', data: payload, timestamp: Date.now() });
+        const log = { type: 'error', data: payload, timestamp: Date.now() };
+        // error 默认即时上报，除非显式指定 immediate: false
+        const immediate = options?.immediate ?? true;
+        if (immediate) {
+            void this.sendReportLogs([log]).catch(() => {
+                this.cacheFailedReportLogs([log]);
+            });
+        }
+        else {
+            this.report(log);
+        }
     }
     track(trackType, data = {}) {
         if (!trackType)
@@ -665,10 +813,7 @@ class ClsLoggerCore {
      * 立即发送内存队列
      */
     async flushBatch() {
-        if (this.batchTimer) {
-            clearTimeout(this.batchTimer);
-            this.batchTimer = null;
-        }
+        this.cancelScheduledFlush();
         this.batchTimerDueAt = null;
         if (this.memoryQueue.length === 0)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@be-link/cls-logger",
-  "version": "1.0.1-beta.17",
+  "version": "1.0.1-beta.18",
   "description": "@be-link cls-logger - 腾讯云 CLS 日志上报封装",
   "homepage": "https://github.com/snowmountain-top/be-link",
   "author": "zhuiyi",