performance-helper 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { PerformanceHelperOptions, PerformanceMetrics, ResourceInfo, ErrorInfo, ReportData, LongTaskInfo, LongTaskAttribution } from './types';
+import { HighlightOptions } from './utils/index';
+/**
+ * 性能监控 SDK
+ */
+export declare class PerformanceHelper {
+    private options;
+    private reporter;
+    private performanceCollector;
+    private resourceMonitor;
+    private errorMonitor;
+    private initialized;
+    constructor(options: PerformanceHelperOptions);
+    /**
+     * 初始化 SDK
+     */
+    init(): void;
+    /**
+     * 采集并上报性能指标
+     */
+    private collectAndReportPerformance;
+    /**
+     * 手动上报性能指标
+     */
+    reportPerformance(): void;
+    /**
+     * 获取性能指标
+     */
+    getPerformanceMetrics(): PerformanceMetrics;
+    /**
+     * 框出 LCP 元素（用于调试）
+     * 会在 LCP 元素周围添加高亮边框
+     * @param options 高亮选项
+     * @returns 是否成功框出元素
+     */
+    highlightLCPElement(options?: HighlightOptions): boolean;
+    /**
+     * 移除 LCP 元素的高亮
+     */
+    removeLCPHighlight(): void;
+    /**
+     * 获取资源信息
+     */
+    getResources(): ResourceInfo[];
+    /**
+     * 获取慢资源
+     */
+    getSlowResources(threshold?: number): ResourceInfo[];
+    /**
+     * 获取错误信息
+     */
+    getErrors(): ErrorInfo[];
+    /**
+     * 手动上报错误
+     */
+    reportError(error: Error, context?: Record<string, any>): void;
+    /**
+     * 上报自定义数据
+     */
+    reportCustom(type: string, data: any): void;
+    /**
+     * 销毁 SDK
+     */
+    destroy(): void;
+}
+export type { PerformanceHelperOptions, PerformanceMetrics, ResourceInfo, ErrorInfo, ReportData, LongTaskInfo, LongTaskAttribution };
+export default PerformanceHelper;

package/dist/index.js

@@ -0,0 +1,192 @@
+import { PerformanceCollector } from './core/performance';
+import { ResourceMonitor } from './core/resource';
+import { ErrorMonitor } from './core/error';
+import { Reporter } from './core/reporter';
+import { querySelectorByPath, highlightElement, removeElementHighlight } from './utils/index';
+/**
+ * 性能监控 SDK
+ */
+export class PerformanceHelper {
+    constructor(options) {
+        this.initialized = false;
+        if (!options.reportUrl) {
+            throw new Error('reportUrl is required');
+        }
+        this.options = {
+            immediate: false,
+            monitorResources: true,
+            monitorErrors: false,
+            monitorPerformance: true,
+            sampleRate: 1,
+            ...options,
+        };
+        this.reporter = new Reporter(this.options);
+        this.performanceCollector = new PerformanceCollector();
+        this.resourceMonitor = new ResourceMonitor();
+        this.errorMonitor = new ErrorMonitor();
+        // 立即初始化性能观察器（需要在页面加载前设置）
+        if (this.options.monitorPerformance) {
+            this.performanceCollector.init();
+        }
+    }
+    /**
+     * 初始化 SDK
+     */
+    init() {
+        if (this.initialized) {
+            console.warn('PerformanceHelper has already been initialized');
+            return;
+        }
+        // 采样率检查
+        if (Math.random() > (this.options.sampleRate || 1)) {
+            return;
+        }
+        // 启动监控
+        if (this.options.monitorResources) {
+            this.resourceMonitor.start();
+        }
+        if (this.options.monitorErrors) {
+            this.errorMonitor.start();
+        }
+        if (this.options.monitorPerformance) {
+            // 等待页面加载完成后采集性能指标
+            if (document.readyState === 'complete') {
+                this.collectAndReportPerformance();
+            }
+            else {
+                window.addEventListener('load', () => {
+                    // 延迟采集，确保所有指标都已计算完成
+                    setTimeout(() => {
+                        this.collectAndReportPerformance();
+                    }, 2000);
+                });
+            }
+        }
+        this.initialized = true;
+    }
+    /**
+     * 采集并上报性能指标
+     */
+    collectAndReportPerformance() {
+        const metrics = this.performanceCollector.collect();
+        this.reporter.report({
+            type: 'performance',
+            data: metrics,
+        });
+    }
+    /**
+     * 手动上报性能指标
+     */
+    reportPerformance() {
+        const metrics = this.performanceCollector.collect();
+        this.reporter.report({
+            type: 'performance',
+            data: metrics,
+        });
+    }
+    /**
+     * 获取性能指标
+     */
+    getPerformanceMetrics() {
+        return this.performanceCollector.collect();
+    }
+    /**
+     * 框出 LCP 元素（用于调试）
+     * 会在 LCP 元素周围添加高亮边框
+     * @param options 高亮选项
+     * @returns 是否成功框出元素
+     */
+    highlightLCPElement(options) {
+        const metrics = this.getPerformanceMetrics();
+        const lcpElementPath = metrics.lcpElement;
+        if (!lcpElementPath) {
+            console.warn('LCP element path not found');
+            return false;
+        }
+        // 根据路径查找元素
+        const element = querySelectorByPath(lcpElementPath);
+        if (!element) {
+            console.warn(`LCP element not found: ${lcpElementPath}`);
+            return false;
+        }
+        // 使用工具函数高亮元素
+        const removeHighlight = highlightElement(element, options);
+        if (!removeHighlight) {
+            console.warn(`LCP element is not an HTMLElement: ${lcpElementPath}`);
+            return false;
+        }
+        // 保存移除函数到元素上（方便调试）
+        element.__removeLCPHighlight = removeHighlight;
+        console.log('LCP element highlighted:', element, lcpElementPath);
+        return true;
+    }
+    /**
+     * 移除 LCP 元素的高亮
+     */
+    removeLCPHighlight() {
+        const metrics = this.getPerformanceMetrics();
+        const lcpElementPath = metrics.lcpElement;
+        if (!lcpElementPath) {
+            return;
+        }
+        const element = querySelectorByPath(lcpElementPath);
+        if (element) {
+            removeElementHighlight(element);
+            // 同时清理 LCP 特定的引用
+            if (element.__removeLCPHighlight) {
+                delete element.__removeLCPHighlight;
+            }
+        }
+    }
+    /**
+     * 获取资源信息
+     */
+    getResources() {
+        return this.resourceMonitor.getResources();
+    }
+    /**
+     * 获取慢资源
+     */
+    getSlowResources(threshold) {
+        return this.resourceMonitor.getSlowResources(threshold);
+    }
+    /**
+     * 获取错误信息
+     */
+    getErrors() {
+        return this.errorMonitor.getErrors();
+    }
+    /**
+     * 手动上报错误
+     */
+    reportError(error, context) {
+        this.errorMonitor.reportError(error, context);
+        const errors = this.errorMonitor.getErrors();
+        const lastError = errors[errors.length - 1];
+        if (lastError) {
+            this.reporter.report({
+                type: 'error',
+                data: lastError,
+            });
+        }
+    }
+    /**
+     * 上报自定义数据
+     */
+    reportCustom(type, data) {
+        this.reporter.report({
+            type: type,
+            data: data,
+        });
+    }
+    /**
+     * 销毁 SDK
+     */
+    destroy() {
+        this.reporter.destroy();
+        this.performanceCollector.destroy();
+        this.initialized = false;
+    }
+}
+// 默认导出
+export default PerformanceHelper;

package/dist/types/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * SDK 配置选项
+ */
+export interface PerformanceHelperOptions {
+    /** 上报地址 */
+    reportUrl: string;
+    /** 应用ID */
+    appId?: string;
+    /** 用户ID */
+    userId?: string;
+    /** 是否立即上报，默认false（批量上报） */
+    immediate?: boolean;
+    /** 批量上报间隔（毫秒），默认5000 */
+    batchInterval?: number;
+    /** 是否监控资源加载，默认true */
+    monitorResources?: boolean;
+    /** 是否监控错误，默认true */
+    monitorErrors?: boolean;
+    /** 是否监控性能指标，默认true */
+    monitorPerformance?: boolean;
+    /** 采样率 0-1，默认1 */
+    sampleRate?: number;
+}
+/**
+ * 长任务归因信息
+ */
+export interface LongTaskAttribution {
+    /** 任务类型：script, layout, style, paint, composite, other */
+    taskType: string;
+    /** 容器类型：window, iframe, embed, object */
+    containerType?: string;
+    /** 容器名称 */
+    containerName?: string;
+    /** 容器ID */
+    containerId?: string;
+    /** 容器源（URL） */
+    containerSrc?: string;
+    /** 任务名称 */
+    name?: string;
+    /** 脚本URL（如果是脚本执行导致的长任务） */
+    scriptURL?: string;
+    /** 相关DOM元素（如果是DOM操作导致的长任务） */
+    element?: Element;
+    /** 元素路径（CSS选择器路径） */
+    elementPath?: string;
+    /** 元素标签名 */
+    elementTag?: string;
+    /** 元素ID */
+    elementId?: string;
+    /** 元素类名 */
+    elementClass?: string;
+}
+/**
+ * 长任务详细信息
+ */
+export interface LongTaskInfo {
+    /** 开始时间（相对于页面加载） */
+    startTime: number;
+    /** 持续时间（毫秒） */
+    duration: number;
+    /** 归因信息数组 */
+    attribution: LongTaskAttribution[];
+}
+/**
+ * 性能指标数据
+ */
+export interface PerformanceMetrics {
+    /** First Contentful Paint */
+    fcp?: number;
+    /** Largest Contentful Paint */
+    lcp?: number;
+    /** LCP 元素路径 */
+    lcpElement?: string;
+    /** First Input Delay */
+    fid?: number;
+    /** Cumulative Layout Shift */
+    cls?: number;
+    /** Total Blocking Time */
+    tbt?: number;
+    /** Speed Index */
+    speedIndex?: number;
+    /** 长任务列表 */
+    longTasks?: LongTaskInfo[];
+    /** Time to First Byte */
+    ttfb?: number;
+    /** DOM Content Loaded */
+    domContentLoaded?: number;
+    /** Load 完成时间 */
+    load?: number;
+    /** DNS 查询时间 */
+    dns?: number;
+    /** TCP 连接时间 */
+    tcp?: number;
+    /** 请求响应时间 */
+    request?: number;
+    /** 页面解析时间 */
+    parse?: number;
+}
+/**
+ * 资源加载信息
+ */
+export interface ResourceInfo {
+    name: string;
+    type: string;
+    duration: number;
+    size: number;
+    startTime: number;
+    url: string;
+}
+/**
+ * 错误信息
+ */
+export interface ErrorInfo {
+    message: string;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    timestamp: number;
+    url: string;
+    userAgent: string;
+}
+/**
+ * 上报数据
+ */
+export interface ReportData {
+    type: 'performance' | 'resource' | 'error';
+    data: PerformanceMetrics | ResourceInfo | ErrorInfo;
+    timestamp: number;
+    url: string;
+    userAgent: string;
+    appId?: string;
+    userId?: string;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 工具函数集合
+ */
+/**
+ * 获取元素的DOM路径
+ * 生成类似 "html > body > div#app > div.container > img" 的路径字符串
+ *
+ * @param element - DOM元素
+ * @returns 元素的完整DOM路径字符串
+ */
+export declare function getElementPath(element: Element | null): string;
+/**
+ * 根据 CSS 选择器路径查找元素
+ * @param path CSS 选择器路径，例如 "body > div#app > img"
+ * @returns 找到的元素，如果未找到返回 null
+ */
+export declare function querySelectorByPath(path: string): Element | null;
+/**
+ * 检查元素是否匹配选择器
+ */
+export declare function matchesSelector(element: Element, selector: string): boolean;
+/**
+ * 简单的选择器匹配（降级方案）
+ */
+export declare function simpleMatches(element: Element, selector: string): boolean;
+/**
+ * 元素高亮选项
+ */
+export interface HighlightOptions {
+    /** 边框颜色，默认红色 */
+    borderColor?: string;
+    /** 边框宽度，默认 3px */
+    borderWidth?: string;
+    /** 背景颜色，默认透明黄色 */
+    backgroundColor?: string;
+    /** 是否滚动到元素位置，默认 true */
+    scrollIntoView?: boolean;
+}
+/**
+ * 高亮元素
+ * 在元素周围添加高亮边框和背景色
+ * @param element - 要高亮的 HTML 元素
+ * @param options - 高亮选项
+ * @returns 移除高亮的函数，如果元素不是 HTMLElement 则返回 null
+ */
+export declare function highlightElement(element: Element, options?: HighlightOptions): (() => void) | null;
+/**
+ * 移除元素高亮
+ * 如果元素上有保存的移除函数，则调用它
+ * @param element - 要移除高亮的元素
+ */
+export declare function removeElementHighlight(element: Element): void;

package/dist/utils/index.js

@@ -0,0 +1,197 @@
+/**
+ * 工具函数集合
+ */
+/**
+ * 获取元素的DOM路径
+ * 生成类似 "html > body > div#app > div.container > img" 的路径字符串
+ *
+ * @param element - DOM元素
+ * @returns 元素的完整DOM路径字符串
+ */
+export function getElementPath(element) {
+    if (!element) {
+        return '';
+    }
+    const path = [];
+    let current = element;
+    while (current && current.nodeType === Node.ELEMENT_NODE) {
+        let selector = current.tagName.toLowerCase();
+        // 添加ID
+        if (current.id) {
+            selector += `#${current.id}`;
+        }
+        // 添加类名（最多取前3个，避免路径过长）
+        if (current.className && typeof current.className === 'string') {
+            const classes = current.className
+                .trim()
+                .split(/\s+/)
+                .filter((cls) => cls)
+                .slice(0, 3);
+            if (classes.length > 0) {
+                selector += `.${classes.join('.')}`;
+            }
+        }
+        // 如果没有ID和类名，添加索引
+        if (!current.id && (!current.className || current.className.trim() === '')) {
+            const parent = current.parentElement;
+            if (parent) {
+                const siblings = Array.from(parent.children);
+                const index = siblings.indexOf(current);
+                if (index >= 0) {
+                    selector += `:nth-child(${index + 1})`;
+                }
+            }
+        }
+        path.unshift(selector);
+        // 向上遍历到html为止（包括body和html）
+        current = current.parentElement;
+        if (current && current.tagName === 'HTML') {
+            // 如果当前是html，已经添加到路径，停止遍历
+            break;
+        }
+    }
+    return path.join(' > ');
+}
+/**
+ * 根据 CSS 选择器路径查找元素
+ * @param path CSS 选择器路径，例如 "body > div#app > img"
+ * @returns 找到的元素，如果未找到返回 null
+ */
+export function querySelectorByPath(path) {
+    if (!path) {
+        return null;
+    }
+    try {
+        // 尝试直接使用 querySelector
+        const element = document.querySelector(path);
+        if (element) {
+            return element;
+        }
+        // 如果直接查询失败，尝试分段查找
+        // 路径格式通常是 "html > body > div#id.class > img"
+        const parts = path.split(' > ');
+        let current = document.documentElement;
+        for (const part of parts) {
+            if (!current) {
+                return null;
+            }
+            // 尝试在当前元素下查找
+            const found = current.querySelector(part);
+            if (found && current.contains(found)) {
+                current = found;
+            }
+            else {
+                // 如果查询失败，尝试直接匹配当前元素
+                if (matchesSelector(current, part)) {
+                    continue;
+                }
+                return null;
+            }
+        }
+        return current;
+    }
+    catch (e) {
+        console.error('Error querying element by path:', path, e);
+        return null;
+    }
+}
+/**
+ * 检查元素是否匹配选择器
+ */
+export function matchesSelector(element, selector) {
+    try {
+        return element.matches(selector);
+    }
+    catch (e) {
+        // 降级方案：手动解析简单的选择器
+        return simpleMatches(element, selector);
+    }
+}
+/**
+ * 简单的选择器匹配（降级方案）
+ */
+export function simpleMatches(element, selector) {
+    // 移除空格
+    selector = selector.trim();
+    // 检查标签名
+    if (selector.includes('#')) {
+        const [tag, id] = selector.split('#');
+        if (tag && element.tagName.toLowerCase() !== tag.toLowerCase()) {
+            return false;
+        }
+        if (id && element.id !== id.split('.')[0]) {
+            return false;
+        }
+    }
+    else if (selector.includes('.')) {
+        const [tag, classes] = selector.split('.');
+        if (tag && element.tagName.toLowerCase() !== tag.toLowerCase()) {
+            return false;
+        }
+        if (classes) {
+            const classList = classes.split('.');
+            for (const cls of classList) {
+                if (cls && !element.classList.contains(cls)) {
+                    return false;
+                }
+            }
+        }
+    }
+    else {
+        if (element.tagName.toLowerCase() !== selector.toLowerCase()) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 高亮元素
+ * 在元素周围添加高亮边框和背景色
+ * @param element - 要高亮的 HTML 元素
+ * @param options - 高亮选项
+ * @returns 移除高亮的函数，如果元素不是 HTMLElement 则返回 null
+ */
+export function highlightElement(element, options) {
+    if (!(element instanceof HTMLElement)) {
+        return null;
+    }
+    // 设置高亮样式
+    const { borderColor = '#ff0000', borderWidth = '3px', backgroundColor = 'rgba(255, 255, 0, 0.2)', scrollIntoView = true, } = options || {};
+    // 保存原始样式
+    const originalOutline = element.style.outline;
+    const originalBoxShadow = element.style.boxShadow;
+    const originalBackgroundColor = element.style.backgroundColor;
+    const originalZIndex = element.style.zIndex;
+    const originalPosition = element.style.position;
+    // 应用高亮样式
+    element.style.outline = `${borderWidth} solid ${borderColor}`;
+    element.style.boxShadow = `0 0 0 ${borderWidth} ${borderColor}`;
+    element.style.backgroundColor = backgroundColor;
+    element.style.zIndex = '9999';
+    if (getComputedStyle(element).position === 'static') {
+        element.style.position = 'relative';
+    }
+    // 滚动到元素位置
+    if (scrollIntoView) {
+        element.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+    // 返回移除高亮的函数
+    return () => {
+        element.style.outline = originalOutline;
+        element.style.boxShadow = originalBoxShadow;
+        element.style.backgroundColor = originalBackgroundColor;
+        element.style.zIndex = originalZIndex;
+        element.style.position = originalPosition;
+    };
+}
+/**
+ * 移除元素高亮
+ * 如果元素上有保存的移除函数，则调用它
+ * @param element - 要移除高亮的元素
+ */
+export function removeElementHighlight(element) {
+    if (element instanceof HTMLElement && element.__removeHighlight) {
+        element.__removeHighlight();
+        delete element.__removeHighlight;
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "performance-helper",
+  "version": "1.0.0",
+  "description": "前端性能监控 SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "serve": "node examples/server.js",
+    "start": "npm run build && npm run serve"
+  },
+  "keywords": [
+    "performance",
+    "monitoring",
+    "sdk",
+    "frontend"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist"
+  ]
+}
+