node-pdf2img 0.1.1

package/src/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @tencent/pdf2img - 高性能 PDF 转图片工具
+ */
+
+export interface RenderOptions {
+    /** 目标渲染宽度（像素），默认：1280 */
+    targetWidth?: number;
+    /** 图片密集型页面的目标宽度（像素），默认：1024 */
+    imageHeavyWidth?: number;
+    /** 最大渲染缩放比例，默认：4.0 */
+    maxScale?: number;
+    /** WebP 质量 0-100，默认：70 */
+    webpQuality?: number;
+    /** 启用扫描件检测，默认：true */
+    detectScan?: boolean;
+}
+
+export interface CosConfig {
+    /** 腾讯云 SecretId */
+    secretId: string;
+    /** 腾讯云 SecretKey */
+    secretKey: string;
+    /** COS 存储桶名称 */
+    bucket: string;
+    /** COS 地域 */
+    region: string;
+}
+
+export interface ConvertOptions extends RenderOptions {
+    /** 要转换的页码（1-based），空数组表示全部页面 */
+    pages?: number[];
+    /** 输出类型：'file'、'buffer' 或 'cos' */
+    outputType?: 'file' | 'buffer' | 'cos';
+    /** 输出目录（outputType 为 'file' 时必需） */
+    outputDir?: string;
+    /** 输出文件名前缀，默认：'page' */
+    prefix?: string;
+    /** COS 配置（outputType 为 'cos' 时必需） */
+    cos?: CosConfig;
+    /** COS key 前缀 */
+    cosKeyPrefix?: string;
+}
+
+export interface PageResult {
+    /** 页码（1-based） */
+    pageNum: number;
+    /** 图片宽度（像素） */
+    width: number;
+    /** 图片高度（像素） */
+    height: number;
+    /** 是否成功渲染 */
+    success: boolean;
+    /** 图片 Buffer（outputType 为 'buffer' 时） */
+    buffer?: Buffer;
+    /** 输出文件路径（outputType 为 'file' 时） */
+    outputPath?: string;
+    /** COS key（outputType 为 'cos' 时） */
+    cosKey?: string;
+    /** 图片大小（字节） */
+    size?: number;
+    /** 错误信息（失败时） */
+    error?: string;
+}
+
+export interface ConvertResult {
+    /** 是否成功 */
+    success: boolean;
+    /** PDF 总页数 */
+    numPages: number;
+    /** 成功渲染的页数 */
+    renderedPages: number;
+    /** 页面结果数组 */
+    pages: PageResult[];
+    /** 耗时信息 */
+    timing: {
+        /** 总耗时（毫秒） */
+        total: number;
+        /** 原生渲染器耗时（毫秒） */
+        native: number;
+    };
+}
+
+/**
+ * PDF 转图片
+ *
+ * @param input - PDF 文件路径、URL 或 Buffer
+ * @param options - 转换选项
+ * @returns 转换结果
+ */
+export function convert(input: string | Buffer, options?: ConvertOptions): Promise<ConvertResult>;
+
+/**
+ * 获取 PDF 页数
+ *
+ * @param input - PDF 文件路径或 Buffer
+ * @returns 页数
+ */
+export function getPageCount(input: string | Buffer): number;
+
+/**
+ * 检查原生渲染器是否可用
+ */
+export function isAvailable(): boolean;
+
+/**
+ * 获取版本信息
+ */
+export function getVersion(): string;
+
+/** 输入类型常量 */
+export const InputType: {
+    FILE: 'file';
+    URL: 'url';
+    BUFFER: 'buffer';
+};
+
+/** 输出类型常量 */
+export const OutputType: {
+    FILE: 'file';
+    BUFFER: 'buffer';
+    COS: 'cos';
+};
+
+/** 渲染配置 */
+export const RENDER_CONFIG: {
+    TARGET_RENDER_WIDTH: number;
+    IMAGE_HEAVY_TARGET_WIDTH: number;
+    MAX_RENDER_SCALE: number;
+    WEBP_QUALITY: number;
+    NATIVE_STREAM_THRESHOLD: number;
+};
+
+/** 超时配置 */
+export const TIMEOUT_CONFIG: {
+    RANGE_REQUEST_TIMEOUT: number;
+    DOWNLOAD_TIMEOUT: number;
+};
+
+/** 检查原生渲染器是否可用 */
+export function isNativeAvailable(): boolean;
+
+/** 从 Buffer 渲染 PDF */
+export function renderFromBuffer(
+    pdfBuffer: Buffer,
+    pages?: number[],
+    options?: RenderOptions
+): Promise<{
+    success: boolean;
+    numPages: number;
+    pages: Array<{
+        pageNum: number;
+        width: number;
+        height: number;
+        buffer?: Buffer;
+        success: boolean;
+        error?: string;
+        renderTime: number;
+        encodeTime: number;
+    }>;
+    totalTime: number;
+    nativeTime: number;
+}>;
+
+/** 从流渲染 PDF（用于远程 URL） */
+export function renderFromStream(
+    pdfUrl: string,
+    pdfSize: number,
+    pages?: number[],
+    options?: RenderOptions
+): Promise<{
+    success: boolean;
+    numPages: number;
+    pages: Array<{
+        pageNum: number;
+        width: number;
+        height: number;
+        buffer?: Buffer;
+        success: boolean;
+        error?: string;
+        renderTime: number;
+        encodeTime: number;
+    }>;
+    totalTime: number;
+    nativeTime: number;
+    streamStats?: object;
+}>;

package/src/index.js

@@ -0,0 +1,58 @@
+/**
+ * @tencent/pdf2img - 高性能 PDF 转图片工具
+ *
+ * 使用 PDFium 原生渲染器实现最佳性能。
+ *
+ * @example
+ * ```javascript
+ * import { convert, getPageCount, isAvailable } from '@tencent/pdf2img';
+ *
+ * // 转换 PDF 为图片（返回 Buffer）
+ * const result = await convert('./document.pdf');
+ * console.log(`转换了 ${result.renderedPages} 页`);
+ *
+ * // 保存到文件
+ * const result = await convert('./document.pdf', {
+ *     outputType: 'file',
+ *     outputDir: './output',
+ * });
+ *
+ * // 转换指定页面
+ * const result = await convert('./document.pdf', {
+ *     pages: [1, 2, 3],
+ *     targetWidth: 1920,
+ *     webpQuality: 80,
+ * });
+ *
+ * // 从 URL 转换（大文件自动使用流式加载）
+ * const result = await convert('https://example.com/document.pdf', {
+ *     outputType: 'file',
+ *     outputDir: './output',
+ * });
+ * ```
+ *
+ * @module @tencent/pdf2img
+ */
+
+export {
+    convert,
+    getPageCount,
+    getPageCountSync,
+    isAvailable,
+    getVersion,
+    getThreadPoolStats,
+    destroyThreadPool,
+    InputType,
+    OutputType,
+} from './core/converter.js';
+
+export { RENDER_CONFIG, TIMEOUT_CONFIG } from './core/config.js';
+
+// 导出原生渲染器工具供高级用法
+export {
+    isNativeAvailable,
+    getPageCount as getPageCountNative,
+    getPageCountFromFile,
+    renderPageToRawBitmap,
+    renderPageToRawBitmapFromBuffer,
+} from './renderers/native.js';

package/src/renderers/native.js

@@ -0,0 +1,331 @@
+/**
+ * Native Renderer - PDFium 原生渲染器
+ *
+ * 支持两种模式：
+ * - Native: 直接加载 PDF Buffer 渲染
+ * - Native Stream: 流式加载 PDF 渲染（适合大文件）
+ */
+
+import { createLogger } from '../utils/logger.js';
+import { mergeConfig, TIMEOUT_CONFIG } from '../core/config.js';
+
+const logger = createLogger('NativeRenderer');
+
+// ==================== Native Renderer 动态导入 ====================
+
+let nativeRenderer = null;
+let nativeAvailable = false;
+
+try {
+    // 从 workspace 的 native-renderer 包导入
+    nativeRenderer = await import('node-pdf2img-native');
+
+    if (nativeRenderer.isPdfiumAvailable()) {
+        nativeAvailable = true;
+
+        try {
+            const warmupTime = nativeRenderer.warmup();
+            logger.info(`Native renderer loaded: ${nativeRenderer.getVersion()}, warmup: ${warmupTime}ms`);
+        } catch (warmupErr) {
+            logger.warn(`Native renderer warmup failed: ${warmupErr.message}`);
+        }
+    } else {
+        logger.warn('Native renderer loaded but PDFium library not available');
+    }
+} catch (e) {
+    logger.warn(`Native renderer not available: ${e.message}`);
+    nativeRenderer = {};
+    nativeAvailable = false;
+}
+
+/**
+ * 检查 Native Renderer 是否可用
+ */
+export function isNativeAvailable() {
+    return nativeAvailable;
+}
+
+/**
+ * 获取 PDF 页数（从 Buffer）
+ * @param {Buffer} pdfBuffer - PDF 文件数据
+ * @returns {number} 页数
+ */
+export function getPageCount(pdfBuffer) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+    return nativeRenderer.getPageCount(pdfBuffer);
+}
+
+/**
+ * 获取 PDF 页数（从文件路径）
+ * 
+ * 直接从文件读取，避免在 Node.js 堆中创建大 Buffer
+ * 
+ * @param {string} filePath - PDF 文件路径
+ * @returns {number} 页数
+ */
+export function getPageCountFromFile(filePath) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+    return nativeRenderer.getPageCountFromFile(filePath);
+}
+
+/**
+ * 渲染单页到原始位图（不编码）
+ * 
+ * 只进行 PDFium 渲染，跳过图像编码步骤，返回原始 RGBA 像素数据。
+ * 编码工作可以交给 Sharp 等更高效的库处理。
+ * 
+ * @param {string} filePath - PDF 文件路径
+ * @param {number} pageNum - 页码（从 1 开始）
+ * @param {Object} options - 渲染选项
+ * @returns {Object} { success, buffer, width, height, channels, renderTime, error }
+ */
+export function renderPageToRawBitmap(filePath, pageNum, options = {}) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+    const config = mergeConfig(options);
+    return nativeRenderer.renderPageToRawBitmap(filePath, pageNum, config);
+}
+
+/**
+ * 从 Buffer 渲染单页到原始位图（不编码）
+ * 
+ * @param {Buffer} pdfBuffer - PDF 文件数据
+ * @param {number} pageNum - 页码（从 1 开始）
+ * @param {Object} options - 渲染选项
+ * @returns {Object} { success, buffer, width, height, channels, renderTime, error }
+ */
+export function renderPageToRawBitmapFromBuffer(pdfBuffer, pageNum, options = {}) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+    const config = mergeConfig(options);
+    const buffer = Buffer.isBuffer(pdfBuffer) ? pdfBuffer : Buffer.from(pdfBuffer);
+    return nativeRenderer.renderPageToRawBitmapFromBuffer(buffer, pageNum, config);
+}
+
+/**
+ * 获取版本信息
+ */
+export function getVersion() {
+    if (!nativeAvailable) {
+        return 'Native renderer not available';
+    }
+    return nativeRenderer.getVersion();
+}
+
+/**
+ * 使用 Native Renderer 渲染 PDF Buffer
+ *
+ * @param {Buffer} pdfBuffer - PDF 文件数据
+ * @param {number[]} pages - 要渲染的页码数组（1-based），空数组表示全部页面
+ * @param {Object} options - 渲染选项
+ * @returns {Promise<Object>} 渲染结果
+ */
+export async function renderFromBuffer(pdfBuffer, pages = [], options = {}) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+
+    const config = mergeConfig(options);
+    const buffer = Buffer.isBuffer(pdfBuffer) ? pdfBuffer : Buffer.from(pdfBuffer);
+    const numPages = nativeRenderer.getPageCount(buffer);
+
+    // 确定目标页码
+    let targetPages;
+    if (pages.length === 0) {
+        targetPages = Array.from({ length: numPages }, (_, i) => i + 1);
+    } else {
+        targetPages = pages.filter(p => p >= 1 && p <= numPages);
+    }
+
+    logger.debug(`Rendering ${targetPages.length} pages from buffer (${(buffer.length / 1024 / 1024).toFixed(2)}MB)`);
+
+    const startTime = Date.now();
+    const result = nativeRenderer.renderPages(buffer, targetPages, config);
+
+    if (!result.success) {
+        throw new Error(result.error || 'Native renderer failed');
+    }
+
+    return {
+        success: true,
+        numPages,
+        pages: result.pages.map(page => ({
+            pageNum: page.pageNum,
+            width: page.width,
+            height: page.height,
+            buffer: page.success ? page.buffer : undefined,
+            success: page.success,
+            error: page.error,
+            renderTime: page.renderTime,
+            encodeTime: page.encodeTime,
+        })),
+        totalTime: Date.now() - startTime,
+        nativeTime: result.totalTime,
+    };
+}
+
+/**
+ * 使用 Native Renderer 渲染 PDF 文件
+ * 
+ * 直接从文件路径读取，避免在 Node.js 堆中创建大 Buffer。
+ * 这是处理本地文件的最高效方式。
+ *
+ * @param {string} filePath - PDF 文件路径
+ * @param {number[]} pages - 要渲染的页码数组（1-based），空数组表示全部页面
+ * @param {Object} options - 渲染选项
+ * @returns {Promise<Object>} 渲染结果
+ */
+export async function renderFromFile(filePath, pages = [], options = {}) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+
+    const config = mergeConfig(options);
+    const numPages = nativeRenderer.getPageCountFromFile(filePath);
+
+    // 确定目标页码
+    let targetPages;
+    if (pages.length === 0) {
+        targetPages = Array.from({ length: numPages }, (_, i) => i + 1);
+    } else {
+        targetPages = pages.filter(p => p >= 1 && p <= numPages);
+    }
+
+    logger.debug(`Rendering ${targetPages.length} pages from file: ${filePath}`);
+
+    const startTime = Date.now();
+    const result = nativeRenderer.renderPagesFromFile(filePath, targetPages, config);
+
+    if (!result.success) {
+        throw new Error(result.error || 'Native renderer failed');
+    }
+
+    return {
+        success: true,
+        numPages,
+        pages: result.pages.map(page => ({
+            pageNum: page.pageNum,
+            width: page.width,
+            height: page.height,
+            buffer: page.success ? page.buffer : undefined,
+            success: page.success,
+            error: page.error,
+            renderTime: page.renderTime,
+            encodeTime: page.encodeTime,
+        })),
+        totalTime: Date.now() - startTime,
+        nativeTime: result.totalTime,
+    };
+}
+
+/**
+ * 使用 Native Stream 渲染远程 PDF
+ *
+ * 通过回调按需获取 PDF 数据，避免一次性下载整个文件
+ *
+ * @param {string} pdfUrl - PDF 文件 URL
+ * @param {number} pdfSize - PDF 文件大小
+ * @param {number[]} pages - 要渲染的页码数组（1-based），空数组表示全部页面
+ * @param {Object} options - 渲染选项
+ * @returns {Promise<Object>} 渲染结果
+ */
+export async function renderFromStream(pdfUrl, pdfSize, pages = [], options = {}) {
+    if (!nativeAvailable) {
+        throw new Error('Native renderer not available');
+    }
+
+    if (!pdfUrl || !pdfSize) {
+        throw new Error('pdfUrl and pdfSize are required for stream mode');
+    }
+
+    const config = mergeConfig(options);
+
+    logger.debug(`Stream rendering from ${pdfUrl} (${(pdfSize / 1024 / 1024).toFixed(2)}MB)`);
+
+    /**
+     * fetcher 回调函数 - 被 Rust 通过 ThreadsafeFunction 调用
+     */
+    const fetcher = (error, req) => {
+        if (error) {
+            logger.error(`Fetcher received error: ${error.message}`);
+            return;
+        }
+
+        const { offset, size, requestId } = req;
+        const start = Number(offset);
+        const end = start + size - 1;
+
+        fetch(pdfUrl, {
+            headers: { 'Range': `bytes=${start}-${end}` },
+            signal: AbortSignal.timeout(TIMEOUT_CONFIG.RANGE_REQUEST_TIMEOUT),
+        })
+            .then(response => {
+                if (!response.ok && response.status !== 206) {
+                    throw new Error(`Range request failed with status ${response.status}`);
+                }
+                return response.arrayBuffer();
+            })
+            .then(data => {
+                nativeRenderer.completeStreamRequest(requestId, Buffer.from(data), null);
+            })
+            .catch(err => {
+                logger.error(`Fetcher failed (offset=${start}, size=${size}): ${err.message}`);
+                nativeRenderer.completeStreamRequest(requestId, null, err.message);
+            });
+    };
+
+    const startTime = Date.now();
+
+    // 首次调用获取页数
+    let result = await nativeRenderer.renderPagesFromStream(
+        pdfSize,
+        pages,
+        config,
+        fetcher
+    );
+
+    if (!result.success) {
+        throw new Error(result.error || 'Native stream renderer failed');
+    }
+
+    const numPages = result.numPages;
+
+    // 如果需要渲染所有页面但之前不知道页数
+    if (pages.length === 0 && numPages > 0 && result.pages.length === 0) {
+        const allPages = Array.from({ length: numPages }, (_, i) => i + 1);
+        result = await nativeRenderer.renderPagesFromStream(
+            pdfSize,
+            allPages,
+            config,
+            fetcher
+        );
+
+        if (!result.success) {
+            throw new Error(result.error || 'Native stream renderer failed');
+        }
+    }
+
+    return {
+        success: true,
+        numPages,
+        pages: result.pages.map(page => ({
+            pageNum: page.pageNum,
+            width: page.width,
+            height: page.height,
+            buffer: page.success ? page.buffer : undefined,
+            success: page.success,
+            error: page.error,
+            renderTime: page.renderTime,
+            encodeTime: page.encodeTime,
+        })),
+        totalTime: Date.now() - startTime,
+        nativeTime: result.totalTime,
+        streamStats: result.streamStats,
+    };
+}

package/src/utils/logger.js

@@ -0,0 +1,58 @@
+/**
+ * 简化日志模块
+ */
+
+const IS_DEBUG = process.env.DEBUG === 'true' || process.env.PDF2IMG_DEBUG === 'true';
+
+const colors = {
+    reset: '\x1b[0m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+};
+
+/**
+ * 创建日志实例
+ * @param {string} module - 模块名称
+ */
+export function createLogger(module) {
+    const prefix = `[${module}]`;
+
+    return {
+        info: (msg, data) => {
+            if (IS_DEBUG) {
+                const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+                console.log(`${colors.green}${prefix}${colors.reset} ${msg}${dataStr}`);
+            }
+        },
+
+        warn: (msg, data) => {
+            const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+            console.warn(`${colors.yellow}${prefix}${colors.reset} ${msg}${dataStr}`);
+        },
+
+        error: (msg, data) => {
+            const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+            console.error(`${colors.red}${prefix}${colors.reset} ${msg}${dataStr}`);
+        },
+
+        debug: (msg, data) => {
+            if (IS_DEBUG) {
+                const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+                console.log(`${colors.dim}${prefix}${colors.reset} ${msg}${dataStr}`);
+            }
+        },
+
+        perf: (msg, data) => {
+            if (IS_DEBUG) {
+                const dataStr = data ? ` ${JSON.stringify(data)}` : '';
+                console.log(`${colors.cyan}${prefix}${colors.reset} ${msg}${dataStr}`);
+            }
+        },
+    };
+}
+
+export const IS_DEV = process.env.NODE_ENV !== 'production';
+export const IS_TEST = process.env.NODE_ENV === 'test';