douyin-downloader 0.1.0

package/dist/src/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/performance.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 通用性能監測工具
+ * 提供高級性能監測和分析功能
+ */
+/**
+ * 性能監測器接口
+ */
+export interface PerformanceMonitor {
+    mark(name: string): void;
+    measure(name: string, startMark: string, endMark: string): number;
+    getMeasurements(): Record<string, number>;
+    finalize(): Record<string, number>;
+}
+/**
+ * 性能監測選項
+ */
+export interface PerformanceMonitorOptions {
+    name: string;
+    autoLog?: boolean;
+    logResults?: boolean;
+    keepHistory?: boolean;
+    maxHistoryLength?: number;
+}
+/**
+ * 性能監測器實現
+ * 用於測量和分析代碼執行性能
+ */
+export declare class PerformanceMonitor {
+    private startTime;
+    private active;
+    private markers;
+    private measurements;
+    private history;
+    private readonly options;
+    /**
+     * 創建性能監測器
+     * @param options 性能監測選項
+     */
+    constructor(options: PerformanceMonitorOptions);
+    /**
+     * 獲取性能歷史記錄
+     * @returns 性能歷史記錄
+     */
+    getHistory(): Array<{
+        name: string;
+        duration: number;
+        timestamp: number;
+    }>;
+    /**
+     * 監測異步函數執行性能
+     * @param name 操作名稱
+     * @param fn 要監測的異步函數
+     * @returns Promise 解析為函數返回值和性能數據
+     */
+    static monitor<T>(name: string, fn: () => Promise<T>, options?: Partial<PerformanceMonitorOptions>): Promise<{
+        result: T;
+        performance: Record<string, number>;
+    }>;
+    /**
+     * 創建性能監測裝飾器
+     * 用於裝飾類方法並監測其性能
+     * @param options 性能監測選項
+     * @returns 方法裝飾器
+     */
+    static monitorMethod(options?: Partial<PerformanceMonitorOptions>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+}
+/**
+ * 全局性能監測器工廠
+ */
+export declare class PerformanceMonitorFactory {
+    private static monitors;
+    /**
+     * 創建或獲取性能監測器
+     * @param name 監測器名稱
+     * @param options 性能監測選項
+     * @returns 性能監測器實例
+     */
+    static getMonitor(name: string, options?: Partial<Omit<PerformanceMonitorOptions, 'name'>>): PerformanceMonitor;
+    /**
+     * 結束所有活躍的監測器
+     * @returns 所有監測器的結果
+     */
+    static finalizeAll(): Record<string, Record<string, number>>;
+}
+/**
+ * 監測函數執行時間的簡單工具
+ * @param name 操作名稱
+ * @param fn 要監測的函數
+ * @returns 函數返回值
+ */
+export declare function time<T>(name: string, fn: () => T): T;
+/**
+ * 監測異步函數執行時間的簡單工具
+ * @param name 操作名稱
+ * @param fn 要監測的異步函數
+ * @returns Promise 解析為函數返回值
+ */
+export declare function timeAsync<T>(name: string, fn: () => Promise<T>): Promise<T>;

package/dist/src/utils/performance.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * 通用性能監測工具
+ * 提供高級性能監測和分析功能
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerformanceMonitorFactory = exports.PerformanceMonitor = void 0;
+exports.time = time;
+exports.timeAsync = timeAsync;
+const logger_1 = require("./logger"); // Use the utils logger
+const perf_hooks_1 = require("perf_hooks"); // Use Node.js's performance API
+/**
+ * 性能監測器實現
+ * 用於測量和分析代碼執行性能
+ */
+class PerformanceMonitor {
+    startTime;
+    active = true;
+    markers = new Map();
+    measurements = new Map();
+    history = [];
+    options;
+    /**
+     * 創建性能監測器
+     * @param options 性能監測選項
+     */
+    constructor(options) {
+        this.options = {
+            name: options.name,
+            autoLog: options.autoLog ?? false,
+            logResults: options.logResults ?? true,
+            keepHistory: options.keepHistory ?? false,
+            maxHistoryLength: options.maxHistoryLength ?? 100
+        };
+        this.startTime = perf_hooks_1.performance.now();
+        this.markers.set('start', this.startTime);
+        if (this.options.autoLog) {
+            logger_1.utilsLogger.debug(`[性能監測] ${this.options.name}: 開始監測`);
+        }
+    }
+    /**
+     * 設置標記點
+     * @param name 標記名稱
+     */
+    mark(name) {
+        if (!this.active) {
+            logger_1.utilsLogger.warn(`[性能監測] ${this.options.name}: 嘗試在已結束的監測器上設置標記 ${name}`);
+            return;
+        }
+        const time = perf_hooks_1.performance.now();
+        this.markers.set(name, time);
+        if (this.options.autoLog) {
+            const elapsed = time - this.startTime;
+            logger_1.utilsLogger.debug(`[性能監測] ${this.options.name}: 標記 ${name} 設置於 +${elapsed.toFixed(2)}ms`);
+        }
+    }
+    /**
+     * 測量兩個標記點之間的耗時
+     * @param name 測量名稱
+     * @param startMark 開始標記名稱
+     * @param endMark 結束標記名稱
+     * @returns 測量結果（毫秒）
+     */
+    measure(name, startMark, endMark) {
+        if (!this.markers.has(startMark) || !this.markers.has(endMark)) {
+            logger_1.utilsLogger.warn(`[性能監測] ${this.options.name}: 無法測量 ${startMark} 到 ${endMark}，缺少標記點`);
+            return -1;
+        }
+        const startTime = this.markers.get(startMark);
+        const endTime = this.markers.get(endMark);
+        const duration = endTime - startTime;
+        this.measurements.set(name, duration);
+        if (this.options.keepHistory) {
+            this.history.push({
+                name,
+                duration,
+                timestamp: Date.now()
+            });
+            // 保持歷史記錄在限制範圍內
+            if (this.history.length > this.options.maxHistoryLength) {
+                this.history.shift();
+            }
+        }
+        if (this.options.autoLog) {
+            logger_1.utilsLogger.debug(`[性能監測] ${this.options.name}: ${name} 耗時 ${duration.toFixed(2)}ms`);
+        }
+        return duration;
+    }
+    /**
+     * 獲取所有測量結果
+     * @returns 測量結果記錄
+     */
+    getMeasurements() {
+        return Object.fromEntries(this.measurements);
+    }
+    /**
+     * 獲取性能歷史記錄
+     * @returns 性能歷史記錄
+     */
+    getHistory() {
+        return [...this.history];
+    }
+    /**
+     * 結束監測並返回結果
+     * @returns 完整測量結果
+     */
+    finalize() {
+        if (!this.active) {
+            logger_1.utilsLogger.warn(`[性能監測] ${this.options.name}: 嘗試結束已經結束的監測器`);
+            return this.getMeasurements();
+        }
+        // 設置結束標記
+        this.mark('end');
+        // 計算總耗時
+        const totalDuration = this.markers.get('end') - this.startTime;
+        const results = {
+            total: totalDuration,
+            ...this.getMeasurements()
+        };
+        // 計算各階段耗時
+        let lastTime = this.startTime;
+        Array.from(this.markers.entries())
+            .filter(([name]) => name !== 'start' && name !== 'end')
+            .sort((a, b) => a[1] - b[1])
+            .forEach(([marker, time]) => {
+            results[`time_to_${marker}`] = time - this.startTime;
+            // Calculate time since last marker, handle potential NaN if lastTime is somehow invalid
+            results[`time_in_${marker}`] = Number.isFinite(lastTime) ? time - lastTime : 0;
+            lastTime = time;
+        });
+        // 標記監測器已結束
+        this.active = false;
+        // 記錄結果
+        if (this.options.logResults) {
+            logger_1.utilsLogger.info(`[性能監測] ${this.options.name}: 完成，總耗時 ${totalDuration.toFixed(2)}ms`, { performance: results });
+        }
+        return results;
+    }
+    /**
+     * 監測異步函數執行性能
+     * @param name 操作名稱
+     * @param fn 要監測的異步函數
+     * @returns Promise 解析為函數返回值和性能數據
+     */
+    static async monitor(name, fn, options) {
+        const monitor = new PerformanceMonitor({
+            name,
+            ...options
+        });
+        try {
+            monitor.mark('functionStart');
+            const result = await fn();
+            monitor.mark('functionEnd');
+            monitor.measure('functionExecution', 'functionStart', 'functionEnd');
+            return {
+                result,
+                performance: monitor.finalize()
+            };
+        }
+        catch (error) {
+            monitor.mark('functionError');
+            monitor.measure('timeToError', 'functionStart', 'functionError');
+            const performance = monitor.finalize();
+            // 重新拋出錯誤，附加性能數據
+            if (error instanceof Error) {
+                error.performance = performance;
+            }
+            throw error;
+        }
+    }
+    /**
+     * 創建性能監測裝飾器
+     * 用於裝飾類方法並監測其性能
+     * @param options 性能監測選項
+     * @returns 方法裝飾器
+     */
+    static monitorMethod(options = {}) {
+        return function (target, propertyKey, descriptor) {
+            const originalMethod = descriptor.value;
+            descriptor.value = function (...args) {
+                const methodName = options.name || `${target.constructor.name}.${propertyKey}`;
+                const monitor = new PerformanceMonitor({
+                    name: methodName,
+                    ...options
+                });
+                try {
+                    const result = originalMethod.apply(this, args);
+                    // 處理異步方法 (Promise)
+                    if (result instanceof Promise) {
+                        return result
+                            .then(value => {
+                            monitor.mark('resolved');
+                            monitor.finalize();
+                            return value;
+                        })
+                            .catch(error => {
+                            monitor.mark('rejected');
+                            monitor.finalize();
+                            throw error;
+                        });
+                    }
+                    // 處理同步方法
+                    monitor.finalize();
+                    return result;
+                }
+                catch (error) {
+                    monitor.mark('error');
+                    monitor.finalize();
+                    throw error;
+                }
+            };
+            return descriptor;
+        };
+    }
+}
+exports.PerformanceMonitor = PerformanceMonitor;
+/**
+ * 全局性能監測器工廠
+ */
+class PerformanceMonitorFactory {
+    static monitors = new Map();
+    /**
+     * 創建或獲取性能監測器
+     * @param name 監測器名稱
+     * @param options 性能監測選項
+     * @returns 性能監測器實例
+     */
+    static getMonitor(name, options = {}) {
+        if (!this.monitors.has(name)) {
+            this.monitors.set(name, new PerformanceMonitor({
+                name,
+                ...options
+            }));
+        }
+        return this.monitors.get(name);
+    }
+    /**
+     * 結束所有活躍的監測器
+     * @returns 所有監測器的結果
+     */
+    static finalizeAll() {
+        const results = {};
+        this.monitors.forEach((monitor, name) => {
+            results[name] = monitor.finalize();
+        });
+        // 清空監測器列表
+        this.monitors.clear();
+        return results;
+    }
+}
+exports.PerformanceMonitorFactory = PerformanceMonitorFactory;
+/**
+ * 監測函數執行時間的簡單工具
+ * @param name 操作名稱
+ * @param fn 要監測的函數
+ * @returns 函數返回值
+ */
+function time(name, fn) {
+    const start = perf_hooks_1.performance.now();
+    try {
+        const result = fn();
+        const end = perf_hooks_1.performance.now();
+        logger_1.utilsLogger.debug(`[時間] ${name}: ${(end - start).toFixed(2)}ms`);
+        return result;
+    }
+    catch (error) {
+        const end = perf_hooks_1.performance.now();
+        logger_1.utilsLogger.debug(`[時間] ${name} (錯誤): ${(end - start).toFixed(2)}ms`);
+        throw error;
+    }
+}
+/**
+ * 監測異步函數執行時間的簡單工具
+ * @param name 操作名稱
+ * @param fn 要監測的異步函數
+ * @returns Promise 解析為函數返回值
+ */
+async function timeAsync(name, fn) {
+    const start = perf_hooks_1.performance.now();
+    try {
+        const result = await fn();
+        const end = perf_hooks_1.performance.now();
+        logger_1.utilsLogger.debug(`[時間] ${name}: ${(end - start).toFixed(2)}ms`);
+        return result;
+    }
+    catch (error) {
+        const end = perf_hooks_1.performance.now();
+        logger_1.utilsLogger.debug(`[時間] ${name} (錯誤): ${(end - start).toFixed(2)}ms`);
+        throw error;
+    }
+}
+//# sourceMappingURL=performance.js.map

package/dist/src/utils/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../../src/utils/performance.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/retry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 通用重試與並發控制工具
+ * 使用 @supercharge/promise-pool 實現並發控制和重試機制
+ */
+/**
+ * 重試選項接口
+ */
+export interface RetryOptions {
+    retries?: number;
+    minDelay?: number;
+    maxDelay?: number;
+    factor?: number;
+    /**
+     * 重試前的回調函數
+     * @param error 導致重試的錯誤
+     * @param attempt 即將進行的嘗試次數 (從 1 開始)
+     */
+    onRetry?: (error: Error, attempt: number) => void;
+    /**
+     * 判斷錯誤是否應該觸發重試的函數
+     * @param error 錯誤對象
+     * @returns boolean 是否應該重試
+     */
+    shouldRetry?: (error: Error) => boolean;
+}
+/**
+ * 帶重試機制的函數執行器
+ * @param fn 要執行的異步函數
+ * @param options 重試選項
+ * @returns Promise<T> 函數執行結果
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * 並發處理選項接口
+ */
+export interface ProcessBatchOptions extends RetryOptions {
+    concurrency?: number;
+    /**
+     * 批處理進度回調
+     * @param completed 已完成的任務數
+     * @param total 總任務數
+     * @param errors 錯誤列表 (如果有的話)
+     */
+    onProgress?: (completed: number, total: number, errors: Error[]) => void;
+}
+/**
+ * 並發執行任務列表，帶重試機制
+ * @param items 要處理的項目數組
+ * @param fn 處理每個項目的異步函數
+ * @param options 執行選項，包括並行數和重試選項
+ * @returns Promise<{ results: R[], errors: Error[] }> 包含成功結果和錯誤的對象
+ */
+export declare function processBatch<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, options?: ProcessBatchOptions): Promise<{
+    results: R[];
+    errors: Error[];
+}>;

package/dist/src/utils/retry.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * 通用重試與並發控制工具
+ * 使用 @supercharge/promise-pool 實現並發控制和重試機制
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+exports.processBatch = processBatch;
+const promise_pool_1 = require("@supercharge/promise-pool");
+const logger_1 = require("./logger"); // Use the utils logger
+const fetch_1 = require("./fetch"); // Import delay from shared fetch utils
+/**
+ * 默認重試選項
+ */
+const DEFAULT_RETRY_OPTIONS = {
+    retries: 3,
+    minDelay: 1000,
+    maxDelay: 30000,
+    factor: 2,
+    onRetry: (error, attempt) => logger_1.utilsLogger.debug(`重試 #${attempt}，原因: ${error.message}`),
+    shouldRetry: (error) => true // 默認重試所有錯誤
+};
+/**
+ * 計算重試延遲時間 (帶指數退避和抖動)
+ * @param attempt 當前嘗試次數（從 1 開始）
+ * @param options 重試選項
+ * @returns 延遲時間（毫秒）
+ */
+function calculateDelay(attempt, options) {
+    const { minDelay, maxDelay, factor } = options;
+    // 指數退避: minDelay * (factor ^ (attempt - 1))
+    let delay = minDelay * Math.pow(factor, attempt - 1);
+    // 添加一些隨機性 (抖動) 以避免 "雷暴" 效應
+    delay = delay * (0.8 + Math.random() * 0.4);
+    // 限制在最大延遲時間內
+    return Math.min(delay, maxDelay);
+}
+/**
+ * 帶重試機制的函數執行器
+ * @param fn 要執行的異步函數
+ * @param options 重試選項
+ * @returns Promise<T> 函數執行結果
+ */
+async function withRetry(fn, options = {}) {
+    const mergedOptions = { ...DEFAULT_RETRY_OPTIONS, ...options };
+    const { retries, onRetry, shouldRetry } = mergedOptions;
+    let attempt = 0;
+    let lastError = new Error("Unknown error during retry");
+    while (attempt <= retries) {
+        try {
+            // 執行函數
+            return await fn();
+        }
+        catch (error) {
+            // 轉換為 Error 對象
+            lastError = error instanceof Error ? error : new Error(String(error));
+            attempt++; // Increment attempt count here
+            // 檢查是否應該重試
+            if (!shouldRetry(lastError)) {
+                logger_1.utilsLogger.warn(`錯誤不可重試: ${lastError.message}`);
+                throw lastError;
+            }
+            // 如果已達到最大重試次數，拋出錯誤
+            if (attempt > retries) {
+                logger_1.utilsLogger.error(`函數執行失敗，已達到最大重試次數 (${retries}): ${lastError.message}`);
+                throw lastError;
+            }
+            // 調用重試回調 (傳遞的是下一次嘗試的序號)
+            onRetry(lastError, attempt);
+            // 計算延遲時間
+            const delayTime = calculateDelay(attempt, mergedOptions);
+            logger_1.utilsLogger.debug(`等待 ${delayTime.toFixed(0)}ms 後重試...`);
+            // 等待後重試
+            await (0, fetch_1.delay)(delayTime);
+            // attempt is already incremented for the next loop iteration
+        }
+    }
+    // 理論上不應該執行到這裡
+    throw lastError;
+}
+/**
+ * 並發執行任務列表，帶重試機制
+ * @param items 要處理的項目數組
+ * @param fn 處理每個項目的異步函數
+ * @param options 執行選項，包括並行數和重試選項
+ * @returns Promise<{ results: R[], errors: Error[] }> 包含成功結果和錯誤的對象
+ */
+async function processBatch(items, fn, options = {}) {
+    const { concurrency = 3, retries = 3, minDelay = 1000, maxDelay = 30000, factor = 2, onRetry = DEFAULT_RETRY_OPTIONS.onRetry, shouldRetry = DEFAULT_RETRY_OPTIONS.shouldRetry, onProgress } = options;
+    let completed = 0;
+    const total = items.length;
+    const allErrors = [];
+    logger_1.utilsLogger.info(`開始並行處理 ${total} 個任務，並行數: ${concurrency}, 重試次數: ${retries}`);
+    const { results, errors } = await promise_pool_1.PromisePool
+        .withConcurrency(concurrency)
+        .for(items)
+        .handleError(async (error, item, pool) => {
+        // PromisePool 的錯誤處理器
+        const err = error instanceof Error ? error : new Error(String(error));
+        allErrors.push(err); // 收集錯誤
+        logger_1.utilsLogger.error(`處理項目失敗 (PromisePool): ${err.message}`, err);
+        // 可以選擇停止池: pool.stop()
+    })
+        .process(async (item, index) => {
+        const result = await withRetry(() => fn(item, index), { retries, minDelay, maxDelay, factor, onRetry, shouldRetry });
+        completed++;
+        if (onProgress) {
+            // 提供實時進度，包括當前錯誤列表
+            onProgress(completed, total, allErrors);
+        }
+        return result;
+    });
+    // PromisePool 的 errors 數組可能包含由 handleError 捕獲的錯誤
+    // 我們已經在 allErrors 中收集了 withRetry 拋出的最終錯誤
+    const finalErrors = allErrors.concat(errors); // 合併兩者以防萬一
+    if (finalErrors.length > 0) {
+        logger_1.utilsLogger.warn(`處理完成，${finalErrors.length}/${total} 個任務最終失敗`);
+        // Optionally log details of each error
+        // finalErrors.forEach((err, i) => logger.debug(`失敗 #${i + 1}: ${err.message}`));
+    }
+    else {
+        logger_1.utilsLogger.info(`成功處理所有 ${total} 個任務`);
+    }
+    // results 數組只包含成功完成的任務的結果
+    return { results: results, errors: finalErrors };
+}
+//# sourceMappingURL=retry.js.map

package/dist/src/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "douyin-downloader",
+  "version": "0.1.0",
+  "description": "抖音影片解析與下載套件",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dydl": "dist/bin/dydl.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x ./dist/bin/dydl.js",
+    "prepublishOnly": "npm run build",
+    "version": "npm run format && git add -A src",
+    "postversion": "git push && git push --tags",
+    "start": "node dist/bin/dydl.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "douyin",
+    "video",
+    "downloader",
+    "parser",
+    "抖音",
+    "影片",
+    "下載",
+    "解析"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gkctou/douyin-downloader.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.14.0",
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "@supercharge/promise-pool": "^3.2.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "env-paths": "^3.0.0",
+    "fs-extra": "^11.3.0",
+    "ora": "^8.2.0",
+    "puppeteer": "^22.15.0",
+    "puppeteer-extra": "^3.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "sanitize-filename": "^1.6.3"
+  }
+}