performance-helper 1.0.0

package/dist/core/performance.js

@@ -0,0 +1,377 @@
+import { getElementPath } from '../utils/index';
+/**
+ * 性能指标采集器
+ */
+export class PerformanceCollector {
+    constructor() {
+        this.metrics = {};
+        this.initialized = false;
+    }
+    /**
+     * 初始化观察器（需要在页面加载前调用）
+     */
+    init() {
+        if (this.initialized) {
+            return;
+        }
+        // 初始化所有性能观察器
+        this.collectWebVitals();
+        this.initialized = true;
+    }
+    /**
+     * 采集所有性能指标
+     */
+    collect() {
+        this.collectNavigationTiming();
+        return { ...this.metrics };
+    }
+    /**
+     * 采集 Navigation Timing 指标
+     * 使用 PerformanceNavigationTiming API（新标准）
+     */
+    collectNavigationTiming() {
+        if (!window.performance || !window.performance.getEntriesByType) {
+            return;
+        }
+        try {
+            const navigationEntries = window.performance.getEntriesByType('navigation');
+            const navigation = navigationEntries[0];
+            if (!navigation) {
+                return;
+            }
+            // DNS 查询时间
+            this.metrics.dns = Math.round(navigation.domainLookupEnd - navigation.domainLookupStart);
+            // TCP 连接时间
+            this.metrics.tcp = Math.round(navigation.connectEnd - navigation.connectStart);
+            // TTFB (Time to First Byte) - 从请求发送到收到第一个字节
+            // 标准定义：responseStart - requestStart
+            // 如果 requestStart 不存在（如缓存），则使用 fetchStart 作为备选
+            this.metrics.ttfb = Math.round(navigation.responseStart - (navigation.requestStart || navigation.fetchStart));
+            // 请求响应时间
+            this.metrics.request = Math.round(navigation.responseEnd - navigation.responseStart);
+            // DOM 解析时间
+            this.metrics.parse = Math.round(navigation.domInteractive - navigation.responseEnd);
+            // DOMContentLoaded 时间
+            // 使用 startTime（对应旧 API 的 navigationStart），表示导航开始的时间
+            // 这比 fetchStart 更准确，因为 startTime 是 PerformanceEntry 的标准属性
+            this.metrics.domContentLoaded = Math.round(navigation.domContentLoadedEventEnd - navigation.startTime);
+            // Load 完成时间
+            // 同样使用 startTime 作为基准，保持一致性
+            this.metrics.load = Math.round(navigation.loadEventEnd - navigation.startTime);
+        }
+        catch (e) {
+            // 浏览器不支持新 API，降级到旧 API
+            this.collectNavigationTimingLegacy();
+        }
+    }
+    /**
+     * 降级方案：使用旧的 PerformanceTiming API（已废弃，仅作兼容）
+     */
+    collectNavigationTimingLegacy() {
+        if (!window.performance || !window.performance.timing) {
+            return;
+        }
+        const timing = window.performance.timing;
+        // DNS 查询时间
+        this.metrics.dns = timing.domainLookupEnd - timing.domainLookupStart;
+        // TCP 连接时间
+        this.metrics.tcp = timing.connectEnd - timing.connectStart;
+        // TTFB (Time to First Byte)
+        this.metrics.ttfb = timing.responseStart - timing.navigationStart;
+        // 请求响应时间
+        this.metrics.request = timing.responseEnd - timing.responseStart;
+        // DOM 解析时间
+        this.metrics.parse = timing.domInteractive - timing.responseEnd;
+        // DOMContentLoaded 时间
+        this.metrics.domContentLoaded = timing.domContentLoadedEventEnd - timing.navigationStart;
+        // Load 完成时间
+        this.metrics.load = timing.loadEventEnd - timing.navigationStart;
+    }
+    /**
+     * 观察 FCP (First Contentful Paint)
+     * 使用 PerformanceObserver 更可靠
+     */
+    observeFCP() {
+        // 先尝试从已有的 paint entries 中读取（适用于页面已加载完成的情况）
+        if (window.performance && window.performance.getEntriesByType) {
+            const paintEntries = window.performance.getEntriesByType('paint');
+            paintEntries.forEach((entry) => {
+                if (entry.name === 'first-contentful-paint') {
+                    this.metrics.fcp = Math.round(entry.startTime);
+                }
+            });
+        }
+        // 如果还没有 FCP 值，使用 PerformanceObserver 观察（适用于页面加载中的情况）
+        if (this.metrics.fcp === undefined && 'PerformanceObserver' in window) {
+            try {
+                this.fcpObserver = new PerformanceObserver((list) => {
+                    const entries = list.getEntries();
+                    entries.forEach((entry) => {
+                        if (entry.name === 'first-contentful-paint') {
+                            this.metrics.fcp = Math.round(entry.startTime);
+                            // 获取到值后可以断开观察
+                            if (this.fcpObserver) {
+                                this.fcpObserver.disconnect();
+                            }
+                        }
+                    });
+                });
+                this.fcpObserver.observe({ type: 'paint', buffered: true });
+            }
+            catch (e) {
+                // 浏览器不支持
+            }
+        }
+    }
+    /**
+     * 初始化所有性能观察器
+     * 在 init() 时调用，用于设置 PerformanceObserver
+     */
+    collectWebVitals() {
+        this.observeFCP();
+        this.observeLCP();
+        this.observeFID();
+        this.observeCLS();
+        this.observeTBT();
+    }
+    /**
+     * 观察 LCP
+     */
+    observeLCP() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            this.lcpObserver = new PerformanceObserver((list) => {
+                var _a, _b;
+                const entries = list.getEntries();
+                const lastEntry = entries[entries.length - 1];
+                // LCP 值计算优先级：
+                // 1. renderTime - 元素实际渲染到屏幕的时间（最准确，适用于图片等资源）
+                // 2. startTime - PerformanceEntry 标准属性（总是存在，适用于文本节点等）
+                // 3. loadTime - 资源加载完成时间（作为最后备选）
+                const lcpValue = (_b = (_a = lastEntry.renderTime) !== null && _a !== void 0 ? _a : lastEntry.startTime) !== null && _b !== void 0 ? _b : lastEntry.loadTime;
+                if (lcpValue) {
+                    this.metrics.lcp = Math.round(lcpValue);
+                    // 记录LCP元素的路径
+                    // LargestContentfulPaint entry 的 element 属性指向导致 LCP 的 DOM 元素
+                    if (lastEntry.element && lastEntry.element instanceof Element) {
+                        const elementPath = getElementPath(lastEntry.element);
+                        if (elementPath) {
+                            this.metrics.lcpElement = elementPath;
+                        }
+                    }
+                }
+            });
+            this.lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });
+        }
+        catch (e) {
+            // 浏览器不支持或已触发
+        }
+    }
+    /**
+     * 观察 FID
+     */
+    observeFID() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            this.fidObserver = new PerformanceObserver((list) => {
+                const entries = list.getEntries();
+                entries.forEach((entry) => {
+                    const eventEntry = entry;
+                    if (eventEntry.processingStart && eventEntry.startTime) {
+                        this.metrics.fid = Math.round(eventEntry.processingStart - eventEntry.startTime);
+                        // FID 只需要第一个输入，获取后可以断开观察
+                        if (this.fidObserver) {
+                            this.fidObserver.disconnect();
+                        }
+                    }
+                });
+            });
+            this.fidObserver.observe({ type: 'first-input', buffered: true });
+        }
+        catch (e) {
+            // 浏览器不支持
+        }
+    }
+    /**
+     * 观察 CLS
+     */
+    observeCLS() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        let clsValue = 0;
+        let clsEntries = [];
+        try {
+            this.clsObserver = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    // layout-shift 类型返回的是 LayoutShift
+                    const layoutShift = entry;
+                    // 只统计没有 recent user input 的布局偏移
+                    if (!layoutShift.hadRecentInput) {
+                        const firstSessionEntry = clsEntries[0];
+                        const lastSessionEntry = clsEntries[clsEntries.length - 1];
+                        // 如果 entry 与上一个 entry 间隔小于 1 秒，且与第一个 entry 间隔小于 5 秒，则合并到当前会话
+                        if (clsValue &&
+                            clsEntries.length > 0 &&
+                            layoutShift.startTime - lastSessionEntry.startTime < 1000 &&
+                            layoutShift.startTime - firstSessionEntry.startTime < 5000) {
+                            clsValue += layoutShift.value;
+                            clsEntries.push(layoutShift);
+                        }
+                        else {
+                            clsValue = layoutShift.value;
+                            clsEntries = [layoutShift];
+                        }
+                    }
+                }
+                this.metrics.cls = Math.round(clsValue * 1000) / 1000;
+            });
+            this.clsObserver.observe({ type: 'layout-shift', buffered: true });
+        }
+        catch (e) {
+            // 浏览器不支持
+        }
+    }
+    /**
+     * 观察长任务并计算 TBT (Total Blocking Time)
+     * TBT = 所有长任务（>50ms）的阻塞时间总和
+     * 阻塞时间 = 任务持续时间 - 50ms
+     */
+    observeTBT() {
+        if (!('PerformanceObserver' in window)) {
+            return;
+        }
+        try {
+            // 初始化长任务数组和 TBT
+            if (!this.metrics.longTasks) {
+                this.metrics.longTasks = [];
+            }
+            this.metrics.tbt = 0;
+            this.longTaskObserver = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    // 长任务定义为超过 50ms 的任务
+                    if (entry.duration > 50) {
+                        const longTaskEntry = entry; // PerformanceLongTaskTiming
+                        // 提取归因信息
+                        const attribution = [];
+                        if (longTaskEntry.attribution && Array.isArray(longTaskEntry.attribution)) {
+                            longTaskEntry.attribution.forEach((attr) => {
+                                const attributionInfo = {
+                                    taskType: attr.entryType || attr.name || 'unknown',
+                                    name: attr.name,
+                                };
+                                // 容器信息（如果是 iframe 等）
+                                if (attr.containerType) {
+                                    attributionInfo.containerType = attr.containerType;
+                                }
+                                if (attr.containerName) {
+                                    attributionInfo.containerName = attr.containerName;
+                                }
+                                if (attr.containerId) {
+                                    attributionInfo.containerId = attr.containerId;
+                                }
+                                if (attr.containerSrc) {
+                                    attributionInfo.containerSrc = attr.containerSrc;
+                                }
+                                // 脚本URL（如果是脚本执行导致的长任务）
+                                if (attr.scriptURL) {
+                                    attributionInfo.scriptURL = attr.scriptURL;
+                                }
+                                // DOM元素信息（如果是DOM操作导致的长任务）
+                                if (attr.element) {
+                                    const element = attr.element;
+                                    attributionInfo.element = element;
+                                    attributionInfo.elementPath = getElementPath(element);
+                                    attributionInfo.elementTag = element.tagName.toLowerCase();
+                                    if (element.id) {
+                                        attributionInfo.elementId = element.id;
+                                    }
+                                    if (element.className && typeof element.className === 'string') {
+                                        attributionInfo.elementClass = element.className.trim();
+                                    }
+                                }
+                                attribution.push(attributionInfo);
+                            });
+                        }
+                        else {
+                            // 如果没有 attribution，尝试从 entry 本身推断
+                            // 某些浏览器可能不支持 attribution，但我们可以从其他信息推断
+                            const fallbackInfo = {
+                                taskType: 'unknown',
+                                name: entry.name || 'long-task',
+                            };
+                            // 尝试从 entry 中提取脚本信息
+                            if (entry.scriptURL) {
+                                fallbackInfo.scriptURL = entry.scriptURL;
+                            }
+                            attribution.push(fallbackInfo);
+                        }
+                        // 添加到长任务列表
+                        const longTaskInfo = {
+                            startTime: Math.round(entry.startTime),
+                            duration: Math.round(entry.duration),
+                            attribution,
+                        };
+                        this.metrics.longTasks.push(longTaskInfo);
+                        // 累加 TBT（阻塞时间 = duration - 50ms）
+                        const blockingTime = Math.round(entry.duration - 50);
+                        this.metrics.tbt = (this.metrics.tbt || 0) + blockingTime;
+                    }
+                }
+            });
+            this.longTaskObserver.observe({ type: 'longtask', buffered: true });
+            // 重新计算 TBT（确保准确性，处理所有 buffered entries）
+            // 因为 buffered: true 会立即触发回调，但为了确保准确性，重新计算一次
+            this.updateTBT();
+        }
+        catch (e) {
+            // 浏览器不支持 longtask API
+        }
+    }
+    /**
+     * 更新 TBT (Total Blocking Time)
+     * 从已收集的长任务列表中重新计算 TBT，确保准确性
+     */
+    updateTBT() {
+        const longTasks = this.metrics.longTasks;
+        if (!longTasks || longTasks.length === 0) {
+            this.metrics.tbt = 0;
+            return;
+        }
+        // 重新计算 TBT（确保准确性）
+        let tbt = 0;
+        longTasks.forEach((task) => {
+            // 只有 duration > 50ms 的任务才计入 TBT
+            // 阻塞时间 = duration - 50ms
+            if (task.duration > 50) {
+                tbt += task.duration - 50;
+            }
+        });
+        this.metrics.tbt = Math.round(tbt);
+    }
+    /**
+     * 销毁观察器
+     */
+    destroy() {
+        if (this.lcpObserver) {
+            this.lcpObserver.disconnect();
+        }
+        if (this.fidObserver) {
+            this.fidObserver.disconnect();
+        }
+        if (this.clsObserver) {
+            this.clsObserver.disconnect();
+        }
+        if (this.fcpObserver) {
+            this.fcpObserver.disconnect();
+        }
+        if (this.longTaskObserver) {
+            this.longTaskObserver.disconnect();
+        }
+        this.initialized = false;
+    }
+}

package/dist/core/reporter.d.ts

@@ -0,0 +1,38 @@
+import { ReportData, PerformanceHelperOptions } from '../types';
+/**
+ * 数据上报器
+ */
+export declare class Reporter {
+    private reportUrl;
+    private appId?;
+    private userId?;
+    private immediate;
+    private batchInterval;
+    private queue;
+    private timer?;
+    constructor(options: PerformanceHelperOptions);
+    /**
+     * 上报数据
+     */
+    report(data: Omit<ReportData, 'timestamp' | 'url' | 'userAgent'>): void;
+    /**
+     * 批量上报
+     */
+    private batchReport;
+    /**
+     * 发送数据
+     */
+    private send;
+    /**
+     * 启动批量定时器
+     */
+    private startBatchTimer;
+    /**
+     * 设置页面卸载时的上报
+     */
+    private setupBeforeUnload;
+    /**
+     * 销毁上报器
+     */
+    destroy(): void;
+}

package/dist/core/reporter.js

@@ -0,0 +1,105 @@
+/**
+ * 数据上报器
+ */
+export class Reporter {
+    constructor(options) {
+        this.queue = [];
+        this.reportUrl = options.reportUrl;
+        this.appId = options.appId;
+        this.userId = options.userId;
+        this.immediate = options.immediate || false;
+        this.batchInterval = options.batchInterval || 5000;
+        if (!this.immediate) {
+            this.startBatchTimer();
+        }
+        // 页面卸载时上报剩余数据
+        this.setupBeforeUnload();
+    }
+    /**
+     * 上报数据
+     */
+    report(data) {
+        const reportData = {
+            ...data,
+            timestamp: Date.now(),
+            url: window.location.href,
+            userAgent: navigator.userAgent,
+            appId: this.appId,
+            userId: this.userId,
+        };
+        if (this.immediate) {
+            this.send([reportData]);
+        }
+        else {
+            this.queue.push(reportData);
+        }
+    }
+    /**
+     * 批量上报
+     */
+    batchReport() {
+        if (this.queue.length === 0) {
+            return;
+        }
+        const dataToSend = [...this.queue];
+        this.queue = [];
+        this.send(dataToSend);
+    }
+    /**
+     * 发送数据
+     */
+    send(data) {
+        // 使用 sendBeacon 优先，fallback 到 fetch
+        if (navigator.sendBeacon) {
+            const blob = new Blob([JSON.stringify(data)], { type: 'application/json' });
+            navigator.sendBeacon(this.reportUrl, blob);
+        }
+        else {
+            // 使用 fetch 发送
+            fetch(this.reportUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(data),
+                keepalive: true,
+            }).catch((error) => {
+                console.error('Report failed:', error);
+                // 发送失败，重新加入队列
+                if (!this.immediate) {
+                    this.queue.push(...data);
+                }
+            });
+        }
+    }
+    /**
+     * 启动批量定时器
+     */
+    startBatchTimer() {
+        this.timer = window.setInterval(() => {
+            this.batchReport();
+        }, this.batchInterval);
+    }
+    /**
+     * 设置页面卸载时的上报
+     */
+    setupBeforeUnload() {
+        window.addEventListener('beforeunload', () => {
+            if (this.queue.length > 0) {
+                // 使用 sendBeacon 确保数据能发送
+                const blob = new Blob([JSON.stringify(this.queue)], { type: 'application/json' });
+                navigator.sendBeacon(this.reportUrl, blob);
+            }
+        });
+    }
+    /**
+     * 销毁上报器
+     */
+    destroy() {
+        if (this.timer) {
+            clearInterval(this.timer);
+        }
+        // 上报剩余数据
+        this.batchReport();
+    }
+}

package/dist/core/resource.d.ts

@@ -0,0 +1,35 @@
+import { ResourceInfo } from '../types';
+/**
+ * 资源加载监控器
+ */
+export declare class ResourceMonitor {
+    private resources;
+    /**
+     * 开始监控资源加载
+     */
+    start(): void;
+    /**
+     * 采集已有资源
+     */
+    private collectExistingResources;
+    /**
+     * 观察资源加载（包括已有和新增的）
+     */
+    private observeNewResources;
+    /**
+     * 添加资源信息
+     */
+    private addResource;
+    /**
+     * 获取资源类型
+     */
+    private getResourceType;
+    /**
+     * 获取所有资源信息
+     */
+    getResources(): ResourceInfo[];
+    /**
+     * 获取慢资源（超过阈值的资源）
+     */
+    getSlowResources(threshold?: number): ResourceInfo[];
+}

package/dist/core/resource.js

@@ -0,0 +1,107 @@
+/**
+ * 资源加载监控器
+ */
+export class ResourceMonitor {
+    constructor() {
+        this.resources = [];
+    }
+    /**
+     * 开始监控资源加载
+     */
+    start() {
+        if (!window.performance || !window.performance.getEntriesByType) {
+            return;
+        }
+        // 监控资源（包括已有和新增的）
+        this.observeNewResources();
+    }
+    /**
+     * 采集已有资源
+     */
+    collectExistingResources() {
+        try {
+            const entries = window.performance.getEntriesByType('resource');
+            entries.forEach((entry) => {
+                this.addResource(entry);
+            });
+        }
+        catch (e) {
+            console.warn('Resource collection failed:', e);
+        }
+    }
+    /**
+     * 观察资源加载（包括已有和新增的）
+     */
+    observeNewResources() {
+        // 如果浏览器不支持 PerformanceObserver，或 observe 失败，降级到 getEntriesByType
+        if (!('PerformanceObserver' in window)) {
+            this.collectExistingResources();
+            return;
+        }
+        try {
+            const observer = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    if (entry.entryType === 'resource') {
+                        this.addResource(entry);
+                    }
+                }
+            });
+            observer.observe({ type: 'resource', buffered: true });
+        }
+        catch (e) {
+            // observe 失败（如参数不支持），降级到 getEntriesByType
+            console.warn('Resource observer failed, fallback to getEntriesByType:', e);
+            this.collectExistingResources();
+        }
+    }
+    /**
+     * 添加资源信息
+     */
+    addResource(entry) {
+        const resourceInfo = {
+            name: entry.name,
+            type: this.getResourceType(entry.name),
+            duration: Math.round(entry.duration),
+            size: entry.transferSize || 0,
+            startTime: Math.round(entry.startTime),
+            url: entry.name,
+        };
+        this.resources.push(resourceInfo);
+    }
+    /**
+     * 获取资源类型
+     */
+    getResourceType(url) {
+        var _a;
+        const extension = ((_a = url.split('.').pop()) === null || _a === void 0 ? void 0 : _a.toLowerCase()) || '';
+        const typeMap = {
+            js: 'script',
+            css: 'stylesheet',
+            png: 'image',
+            jpg: 'image',
+            jpeg: 'image',
+            gif: 'image',
+            svg: 'image',
+            webp: 'image',
+            woff: 'font',
+            woff2: 'font',
+            ttf: 'font',
+            eot: 'font',
+            xml: 'xmlhttprequest',
+            json: 'xmlhttprequest',
+        };
+        return typeMap[extension] || 'other';
+    }
+    /**
+     * 获取所有资源信息
+     */
+    getResources() {
+        return this.resources;
+    }
+    /**
+     * 获取慢资源（超过阈值的资源）
+     */
+    getSlowResources(threshold = 2000) {
+        return this.resources.filter((resource) => resource.duration > threshold);
+    }
+}