wp-epub-gen 0.5.0 → 0.6.0

package/README.md

@@ -122,13 +122,13 @@ epubGen(options).then(result => {
 
 ## API 参考
 
-### epubGen(options, output?)
+### epubGen(options, configs?)
 
 主要的 EPUB 生成函数。
 
 **参数：**
-- `options: IEpubGenOptions` - 配置选项对象
-- `output?: string` - 可选的输出路径，会覆盖 options.output
+- `options: IEpubGenOptions` - 配置选项对象（标题、作者、封面、章节内容等）
+- `configs?: IGenConfigs` - 可选的运行时回调（logger、onProgress、concurrency），见下文 [IGenConfigs](#igenconfigs-运行时回调)
 
 **返回值：**
 - `Promise<IOut>` - 包含生成结果的 Promise
@@ -233,18 +233,83 @@ interface IOut {
 }
 ```
 
+### IGenConfigs 运行时回调
+
+`epubGen` 的第二个参数，用于注入宿主侧的回调和并发配置。所有字段都是可选的。
+
+```typescript
+interface IGenConfigs {
+  logger?: ILogger;
+  onProgress?: (e: IProgressEvent) => void;
+  concurrency?: number;
+}
+```
+
+#### `logger?: ILogger`
+
+注入自定义日志记录器（替代默认 `console`）。常用于 Electron 主进程把日志转发到渲染进程。
+
+```typescript
+interface ILogger {
+  log: (msg: any) => void;
+  info: (msg: any) => void;
+  warn: (msg: any) => void;
+  error: (msg: any) => void;
+}
+```
+
+#### `onProgress?: (e: IProgressEvent) => void`
+
+进度回调。生成过程会在 5 个阶段中分别推送事件，宿主可据此渲染进度条或转发 IPC 给 UI。
+
+```typescript
+type ProgressPhase =
+  | 'parseContent'    // 解析章节 HTML
+  | 'writeChapters'   // 写章节临时文件
+  | 'buildToc'        // 渲染 OPF / NCX / TOC
+  | 'downloadImage'   // 下载图片（仅当存在图片时）
+  | 'zip'             // 打包 .epub
+
+interface IProgressEvent {
+  phase: ProgressPhase;
+  current: number;     // 已完成数量
+  total: number;       // 总数量
+  label?: string;      // 当前条目标签（章节标题 / 图片 URL）
+}
+```
+
+最小用法：
+
+```typescript
+await epubGen(options, {
+  onProgress: (e) => {
+    console.log(`[${e.phase}] ${e.current}/${e.total}`);
+  },
+});
+```
+
+回调中抛出的异常会被库静默吞掉，不会中断 EPUB 生成。
+
+#### `concurrency?: number`
+
+写章节文件和下载图片所共用的并发上限。默认 `16`，机械硬盘或带宽受限场景可调小（如 `4`）。非有限正整数（NaN、负数等）会被自动归一化为默认值。
+
 ## 导出的类型
 
 库导出了所有 TypeScript 类型定义：
 
 ```typescript
-import type { 
-  IEpubGenOptions, 
-  IChapter, 
+import type {
+  IEpubGenOptions,
+  IChapter,
   IChapterData,
   IEpubData,
   IEpubImage,
-  IOut 
+  IGenConfigs,
+  ILogger,
+  IProgressEvent,
+  ProgressPhase,
+  IOut,
 } from 'wp-epub-gen';
 ```
 

package/build/index.cjs

@@ -4,14 +4,14 @@ const os = require("os");
 const path = require("path");
 const url = require("url");
 const uuid = require("uuid");
+const fs = require("fs");
+const util = require("util");
 const cheerio = require("cheerio");
 const diacritics = require("diacritics");
 const uslug = require("uslug");
 const archiver = require("archiver");
 const fs$1 = require("fs-extra");
 const request = require("superagent");
-const fs = require("fs");
-const util = require("util");
 const ejs = require("ejs");
 const entities = require("entities");
 var _documentCurrentScript = typeof document !== "undefined" ? document.currentScript : null;
@@ -95,6 +95,63 @@ class GlobalLogger {
   }
 }
 const logger = GlobalLogger.getInstance();
+util.promisify(fs.readFile);
+const writeFile = util.promisify(fs.writeFile);
+function normalizeConcurrency(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return void 0;
+  return Math.floor(value);
+}
+function pLimit(concurrency) {
+  if (!Number.isFinite(concurrency) || concurrency < 1) concurrency = 1;
+  else concurrency = Math.floor(concurrency);
+  let active = 0;
+  const queue = [];
+  const next = () => {
+    active--;
+    if (queue.length) queue.shift()();
+  };
+  return (fn) => new Promise((resolve, reject) => {
+    const run = () => {
+      active++;
+      fn().then(
+        (v) => {
+          resolve(v);
+          next();
+        },
+        (e) => {
+          reject(e);
+          next();
+        }
+      );
+    };
+    if (active < concurrency) run();
+    else queue.push(run);
+  });
+}
+function emitProgress(configs, event) {
+  if (!configs?.onProgress) return;
+  try {
+    configs.onProgress(event);
+  } catch {
+  }
+}
+const USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.116 Safari/537.36";
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function fileIsStable(filename, max_wait = 3e4) {
+  const start_time = (/* @__PURE__ */ new Date()).getTime();
+  let last_size = fs.statSync(filename).size;
+  while ((/* @__PURE__ */ new Date()).getTime() - start_time <= max_wait) {
+    await wait(1e3);
+    const size = fs.statSync(filename).size;
+    if (size === last_size) return true;
+    last_size = size;
+  }
+  return false;
+}
+function simpleMinifier(xhtml) {
+  xhtml = xhtml.replace(/\s+<\/a>/gi, "</a>").replace(/\n\s+</g, "\n<").replace(/\n+/g, "\n");
+  return xhtml;
+}
 function safeFineName(name) {
   return name.replace(/[/\\?%*:|"<>\t\r\n]/g, "_");
 }
@@ -362,7 +419,7 @@ function loadAndProcessHtml(data) {
     throw new Error("Invalid HTML data: data cannot be empty or whitespace only");
   }
   try {
-    let $ = cheerio__namespace.load(trimmedData, {
+    const $ = cheerio__namespace.load(trimmedData, {
       xmlMode: true,
       // @ts-ignore
       decodeEntities: false,
@@ -372,17 +429,8 @@ function loadAndProcessHtml(data) {
     });
     const body = $("body");
     if (body.length) {
-      const html = body.html();
-      if (html) {
-        $ = cheerio__namespace.load(html, {
-          xmlMode: true,
-          // @ts-ignore
-          decodeEntities: false,
-          lowerCaseTags: true,
-          recognizeSelfClosing: true,
-          lowerCaseAttributeNames: true
-        });
-      }
+      const bodyContents = body.contents();
+      $.root().empty().append(bodyContents);
     }
     return $;
   } catch (error) {
@@ -431,6 +479,10 @@ function processHtmlElements($, allowedAttributes, allowedXhtml11Tags, epubConfi
   });
 }
 function processImages($, chapter, epubConfigs) {
+  if (!epubConfigs._imagesByUrl) {
+    epubConfigs._imagesByUrl = new Map(epubConfigs.images.map((img) => [img.url, img]));
+  }
+  const imagesByUrl = epubConfigs._imagesByUrl;
   $("img").each((index2, elem) => {
     const url2 = $(elem).attr("src") || "";
     if (!url2 || url2.trim().length === 0) {
@@ -446,7 +498,7 @@ function processImages($, chapter, epubConfigs) {
     } catch (error) {
       logger.error(`Error validating image URL "${trimmedUrl}": ${error}`);
     }
-    const image = epubConfigs.images.find((el) => el.url === trimmedUrl);
+    const image = imagesByUrl.get(trimmedUrl);
     let id;
     let extension;
     if (image) {
@@ -485,6 +537,7 @@ function processImages($, chapter, epubConfigs) {
       const dir = chapter.dir || "";
       const img = { id, url: trimmedUrl, dir, mediaType, extension };
       epubConfigs.images.push(img);
+      imagesByUrl.set(trimmedUrl, img);
       if (epubConfigs.verbose) {
         logger.info(`Added image: ${trimmedUrl} -> images/${id}.${extension} (${mediaType})`);
       }
@@ -549,25 +602,6 @@ function parseContent(content, index2, epubConfigs) {
   processChildrenChapters(chapter, index2, epubConfigs);
   return chapter;
 }
-util.promisify(fs.readFile);
-const writeFile = util.promisify(fs.writeFile);
-const USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/34.0.1847.116 Safari/537.36";
-const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function fileIsStable(filename, max_wait = 3e4) {
-  const start_time = (/* @__PURE__ */ new Date()).getTime();
-  let last_size = fs.statSync(filename).size;
-  while ((/* @__PURE__ */ new Date()).getTime() - start_time <= max_wait) {
-    await wait(1e3);
-    const size = fs.statSync(filename).size;
-    if (size === last_size) return true;
-    last_size = size;
-  }
-  return false;
-}
-function simpleMinifier(xhtml) {
-  xhtml = xhtml.replace(/\s+<\/a>/gi, "</a>").replace(/\n\s+</g, "\n<").replace(/\n+/g, "\n");
-  return xhtml;
-}
 const downloadImage = async (epubData, options) => {
   const { url: url2 } = options;
   const { log } = epubData;
@@ -576,7 +610,6 @@ const downloadImage = async (epubData, options) => {
     return;
   }
   const image_dir = path.join(epub_dir, "OEBPS", "images");
-  fs$1.ensureDirSync(image_dir);
   const filename = path.join(image_dir, options.id + "." + options.extension);
   if (url2.startsWith("file://") || url2.startsWith("/")) {
     let aux_path = url2.replace(/^file:\/\//i, "");
@@ -602,35 +635,75 @@ const downloadImage = async (epubData, options) => {
     }
     return;
   }
+  const writeStream = fs$1.createWriteStream(filename);
   let requestAction;
   if (url2.startsWith("http")) {
     requestAction = request.get(url2).set({ "User-Agent": USER_AGENT });
-    requestAction.pipe(fs$1.createWriteStream(filename));
   } else {
     log(`[Copy 2] '${url2}' to '${filename}'`);
     requestAction = fs$1.createReadStream(path.join(options.dir || "", url2));
-    requestAction.pipe(fs$1.createWriteStream(filename));
   }
-  return new Promise((resolve, _reject) => {
+  requestAction.pipe(writeStream);
+  return new Promise((resolve) => {
+    let settled = false;
+    const finalize = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    const cleanupFile = () => {
+      try {
+        fs$1.unlinkSync(filename);
+      } catch {
+      }
+    };
+    const abortSource = () => {
+      if (typeof requestAction.abort === "function") requestAction.abort();
+      else if (typeof requestAction.destroy === "function") requestAction.destroy();
+    };
     requestAction.on("error", (err) => {
       log("[Download Error] Error while downloading: " + url2);
       log(err);
-      fs$1.unlinkSync(filename);
-      resolve();
+      writeStream.destroy();
+      cleanupFile();
+      finalize();
     });
-    requestAction.on("end", () => {
+    writeStream.on("error", (err) => {
+      log("[Write Error] Error while writing: " + filename);
+      log(err);
+      abortSource();
+      cleanupFile();
+      finalize();
+    });
+    writeStream.on("finish", () => {
       log("[Download Success] " + url2);
-      resolve();
+      finalize();
     });
   });
 };
 const downloadAllImages = async (epubData) => {
   const { images } = epubData;
   if (images.length === 0) return;
-  fs$1.ensureDirSync(path.join(epubData.dir, "OEBPS", "images"));
-  for (const image of images) {
-    await downloadImage(epubData, image);
-  }
+  await fs$1.ensureDir(path.join(epubData.dir, "OEBPS", "images"));
+  const concurrency = epubData._configs?.concurrency ?? 16;
+  const limit = pLimit(concurrency);
+  const total = images.length;
+  let done = 0;
+  emitProgress(epubData._configs, { phase: "downloadImage", current: 0, total });
+  await Promise.all(
+    images.map(
+      (image) => limit(async () => {
+        await downloadImage(epubData, image);
+        done++;
+        emitProgress(epubData._configs, {
+          phase: "downloadImage",
+          current: done,
+          total,
+          label: image.url
+        });
+      })
+    )
+  );
 };
 const epub2_content_opf_ejs = `<?xml version="1.0" encoding="UTF-8"?>
 <package xmlns="http://www.idpf.org/2007/opf"
@@ -1029,21 +1102,23 @@ const generateTempFile = async (epubData) => {
   if (epubData.fonts?.length) {
     const fonts_dir = path.join(oebpsDir, "fonts");
     await fs$1.ensureDir(fonts_dir);
-    epubData.fonts = epubData.fonts.map((font) => {
+    const fontFilenames = [];
+    for (const font of epubData.fonts) {
       const filename = path.basename(font);
       if (!fs$1.existsSync(font)) {
         log(`Custom font not found at '${font}'.`);
       } else {
-        fs$1.copySync(font, path.join(fonts_dir, filename));
+        await fs$1.copy(font, path.join(fonts_dir, filename));
       }
-      return filename;
-    });
+      fontFilenames.push(filename);
+    }
+    epubData.fonts = fontFilenames;
   }
   const isAppendTitle = (global_append, local_append) => {
     if (typeof local_append === "boolean") return local_append;
     return !!global_append;
   };
-  const saveContentToFile = (content) => {
+  const renderChapterHtml = (content) => {
     const title = entities__namespace.encodeXML(content.title || "");
     let html = `${epubData.docHeader}
 <head>
@@ -1060,16 +1135,39 @@ const generateTempFile = async (epubData) => {
     html += content.title && content.url ? `<p class="epub-link"><a href="${content.url}">${content.url}</a></p>` : "";
     html += `${content.data}`;
     html += "\n</body>\n</html>";
-    fs$1.ensureDirSync(path.dirname(content.filePath));
-    fs$1.writeFileSync(content.filePath, html, "utf-8");
-    if (Array.isArray(content.children)) {
-      content.children.map(saveContentToFile);
+    return html;
+  };
+  const flattenChapters = (nodes, out = []) => {
+    for (const c of nodes) {
+      out.push(c);
+      if (Array.isArray(c.children) && c.children.length) flattenChapters(c.children, out);
     }
+    return out;
   };
-  epubData.content.map(saveContentToFile);
+  const allChapters = flattenChapters(epubData.content);
+  const totalChapters = allChapters.length;
+  const uniqueDirs = Array.from(new Set(allChapters.map((c) => path.dirname(c.filePath))));
+  for (const d of uniqueDirs) await fs$1.ensureDir(d);
+  const concurrency = epubData._configs?.concurrency ?? 16;
+  const limit = pLimit(concurrency);
+  let written = 0;
+  await Promise.all(
+    allChapters.map(
+      (content) => limit(async () => {
+        await fs$1.writeFile(content.filePath, renderChapterHtml(content), "utf-8");
+        written++;
+        emitProgress(epubData._configs, {
+          phase: "writeChapters",
+          current: written,
+          total: totalChapters,
+          label: content.title
+        });
+      })
+    )
+  );
   const metainf_dir = path.join(epubData.dir, "META-INF");
-  fs$1.ensureDirSync(metainf_dir);
-  fs$1.writeFileSync(
+  await fs$1.ensureDir(metainf_dir);
+  await fs$1.writeFile(
     path.join(metainf_dir, "container.xml"),
     `<?xml version="1.0" encoding="UTF-8" ?>
 <container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
@@ -1079,7 +1177,7 @@ const generateTempFile = async (epubData) => {
   );
   if (epubData.version === 2) {
     const fn = path.join(metainf_dir, "com.apple.ibooks.display-options.xml");
-    fs$1.writeFileSync(
+    await fs$1.writeFile(
       fn,
       `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <display_options>
@@ -1113,17 +1211,25 @@ const generateTempFile = async (epubData) => {
     htmlTocTemplate = epubData.version === 2 ? epub2_toc_xhtml_ejs : epub3_toc_xhtml_ejs;
   }
   const toc_depth = 1;
-  fs$1.writeFileSync(path.join(oebpsDir, "content.opf"), ejs.render(opfTemplate, epubData), "utf-8");
-  fs$1.writeFileSync(
-    path.join(oebpsDir, "toc.ncx"),
-    ejs.render(ncxTocTemplate, { ...epubData, toc_depth }),
-    "utf-8"
-  );
-  fs$1.writeFileSync(
-    path.join(oebpsDir, "toc.xhtml"),
-    simpleMinifier(ejs.render(htmlTocTemplate, epubData)),
-    "utf-8"
-  );
+  emitProgress(epubData._configs, { phase: "buildToc", current: 0, total: 3 });
+  await Promise.all([
+    fs$1.writeFile(
+      path.join(oebpsDir, "content.opf"),
+      ejs.render(opfTemplate, epubData),
+      "utf-8"
+    ),
+    fs$1.writeFile(
+      path.join(oebpsDir, "toc.ncx"),
+      ejs.render(ncxTocTemplate, { ...epubData, toc_depth }),
+      "utf-8"
+    ),
+    fs$1.writeFile(
+      path.join(oebpsDir, "toc.xhtml"),
+      simpleMinifier(ejs.render(htmlTocTemplate, epubData)),
+      "utf-8"
+    )
+  ]);
+  emitProgress(epubData._configs, { phase: "buildToc", current: 3, total: 3 });
 };
 async function makeCover(data) {
   const { cover, _coverExtension, log } = data;
@@ -1181,6 +1287,7 @@ async function genEpub(epubData) {
   const archive = archiver("zip", { zlib: { level: 9 } });
   const outputStream = fs$1.createWriteStream(epubData.output);
   log("Zipping temp dir to " + output);
+  emitProgress(epubData._configs, { phase: "zip", current: 0, total: 1 });
   return new Promise((resolve, reject) => {
     archive.on("end", async () => {
       log("Done zipping, clearing temp dir...");
@@ -1190,6 +1297,7 @@ async function genEpub(epubData) {
       }
       try {
         fs$1.removeSync(dir);
+        emitProgress(epubData._configs, { phase: "zip", current: 1, total: 1 });
         resolve();
       } catch (e) {
         log("[Error] " + e.message);
@@ -1247,7 +1355,7 @@ function check(options) {
   }
   return result(true, void 0, options);
 }
-function parseOptions(options) {
+async function parseOptions(options, configs) {
   const tmpDir = options.tmpDir || os.tmpdir();
   const id = uuid.v4();
   const data = {
@@ -1272,7 +1380,8 @@ function parseOptions(options) {
     docHeader: "",
     images: [],
     content: [],
-    log: (msg) => options.verbose && logger.log(msg)
+    log: (msg) => options.verbose && logger.log(msg),
+    _configs: configs
   };
   if (data.version === 2) {
     data.docHeader = `<?xml version="1.0" encoding="UTF-8"?>
@@ -1291,7 +1400,17 @@ function parseOptions(options) {
   if (typeof data.author === "string") {
     data.author = [data.author];
   }
-  data.content = options.content.map((content, index2) => parseContent(content, index2, data));
+  const total = options.content.length;
+  const parsed = [];
+  for (let i = 0; i < total; i++) {
+    parsed.push(parseContent(options.content[i], i, data));
+    if ((i & 31) === 31) {
+      await new Promise((r) => setImmediate(r));
+      emitProgress(configs, { phase: "parseContent", current: i + 1, total });
+    }
+  }
+  emitProgress(configs, { phase: "parseContent", current: total, total });
+  data.content = parsed;
   if (data.cover) {
     data._coverMediaType = mime.getType(data.cover) || "";
     data._coverExtension = mime.getExtension(data._coverMediaType) || "";
@@ -1299,6 +1418,9 @@ function parseOptions(options) {
   return data;
 }
 async function epubGen(options, configs) {
+  if (configs) {
+    configs = { ...configs, concurrency: normalizeConcurrency(configs.concurrency) };
+  }
   if (configs?.logger) {
     logger.setLogger(configs.logger);
   }
@@ -1312,7 +1434,7 @@ async function epubGen(options, configs) {
   }
   let t;
   try {
-    const data = parseOptions(options);
+    const data = await parseOptions(options, configs);
     const timeoutSeconds = data.timeoutSeconds || 0;
     if (timeoutSeconds > 0) {
       if (verbose) logger.log(`TIMEOUT: ${timeoutSeconds}s`);

package/build/index.d.ts

@@ -12,4 +12,4 @@ declare const _default: {
     };
 };
 export default _default;
-export type { IChapter, IChapterData, IEpubData, IEpubGenOptions, IEpubImage, IOut } from './types';
+export type { IChapter, IChapterData, IEpubData, IEpubGenOptions, IEpubImage, IGenConfigs, ILogger, IOut, IProgressEvent, ProgressPhase, } from './types';