epub2md 1.5.0 → 1.6.0

package/README.md

@@ -13,7 +13,7 @@ Even though the package is primarily intended for CLI is to convert EPUB to Mark
   - Retain the original online image links.
   - Download and localize online images (save remote images locally).
 - **View Information**: Easy to View the basic information, structure, and chapters of the EPUB.
-- **Extraction Function**: Dont need convert, just extract the useful contents of the EPUB file.
+- **Extraction Function**: Just extract the useful contents of the EPUB file.
 
 ## Global Install for CLI
 
@@ -41,10 +41,17 @@ $ npm install @uxiew/epub2md
 # Show usage help
 $ epub2md -h
 
-# Convert directly to markdown format
-$ epub2md ../../fixtures/zhihu.epub
-# or use -m
-$ epub2md -m ../../fixtures/zhihu.epub
+# ========== Basic Conversion ==========
+
+# Convert directly to markdown format (default command)
+$ epub2md book.epub
+$ epub2md /path/to/book.epub
+
+# Convert with autocorrect (spaces and punctuation between Chinese and English)
+$ epub2md -a book.epub
+$ epub2md --autocorrect book.epub
+
+# ========== Batch Conversion (Wildcard Support) ==========
 
 # Convert multiple files using wildcards
 $ epub2md "fixtures/*.epub"
@@ -56,33 +63,58 @@ $ epub2md "fixtures/*.epub" --merge
 
 # Note: Quotes are required around patterns with wildcards to prevent shell expansion
 
-# Convert to markdown and automatically correct spaces and punctuation between Chinese and English (CLI only)
-$ epub2md -M ../../fixtures/zhihu.epub
+# ========== Merge Options ==========
 
-# Convert and directly generate a single merged markdown file (no intermediate files)
-$ epub2md -m ../../fixtures/zhihu.epub --merge
-# You can also use the epub file path as the first parameter directly
-$ epub2md ../../fixtures/zhihu.epub --merge
+# Convert and directly generate a single merged markdown file
+$ epub2md -m book.epub 
+$ epub2md --merge book.epub
 
-# Use --merge=filename.md
-$ epub2md ../../fixtures/zhihu.epub --merge="merged-book.md"
+# Specify custom output filename for merged file
+$ epub2md --merge=custom-name.md book.epub
 
-# By default, DONT downloaded. Basically, the images in the epub are already included, so there is no need to download.
-# However, some epub image links are remote, You will see some warning，maybe they need to be downloaded.
-# Download and localize online images (download remote images to local) (need node > 18.0)
-$ epub2md ../../fixtures/zhihu.epub --localize
+# Merge existing markdown files in a directory (without conversion)
+$ epub2md --merge ./path/to/markdown/dir
 
-# Download and localize online images, while merging all chapters into a single file
-$ epub2md ../../fixtures/zhihu.epub --merge --localize
+# ========== Image Processing ==========
 
-# Merge existing markdown files in a directory
-$ epub2md --merge ./path/to/markdown/dir
+# By default, remote images are NOT downloaded (only a warning is shown)
+# Images embedded in EPUB are always extracted
+
+# Download and localize remote images (requires Node.js >= 18.0)
+$ epub2md -l book.epub
+$ epub2md --localize book.epub
+
+# Combine: convert + merge + download remote images
+$ epub2md -m -l book.epub
+$ epub2md --merge --localize book.epub
+
+# ========== Information Display ==========
+
+# Show basic information (title, author, language)
+$ epub2md -i book.epub
+$ epub2md --info book.epub
+
+# Show structure/table of contents
+$ epub2md -s book.epub
+$ epub2md --structure book.epub
+
+# Show all sections/chapters
+$ epub2md -S book.epub
+$ epub2md --sections book.epub
 
-# Show additional information
-$ epub2md -u ../../fixtures/zhihu.epub  # Extract epub
-$ epub2md -i ../../fixtures/zhihu.epub  # Show basic information
-$ epub2md -S ../../fixtures/zhihu.epub  # Show structure information
-$ epub2md -s ../../fixtures/zhihu.epub  # Show chapter information
+# ========== Extraction ==========
+
+# Extract/unzip EPUB contents
+$ epub2md -u book.epub
+$ epub2md --unzip book.epub
+
+# ========== Command Priority ==========
+
+# Info commands have highest priority
+$ epub2md book.epub --info          # Shows info (doesn't convert)
+$ epub2md --convert --info book.epub # Shows info (info takes precedence)
+
+# Priority order: info/structure/sections > unzip > merge(dir) > convert/autocorrect
 ```
 
 ## Usage
@@ -126,6 +158,22 @@ The return value is an object which contains`structure`, `sections`, `info`(priv
 
 - `Section.prototype.toHtmlObjects`: convert to html object. And a note about `src` and`href`, the`src` and`href` in raw html stay untouched, but the `toHtmlObjects` method resolves `src` to base64 string, and alters `href` so that they make sense in the parsed epub.And the parsed `href` is something like`#{sectionId},{hash}`.
 
+## Testing
+
+```bash
+# Run all tests
+$ npm test
+
+# Run specific test file
+$ npm test -- test/bin.spec.ts
+
+# Run tests with verbose output
+$ npm test -- --reporter=verbose
+
+# Run integration tests only
+$ npm test -- test/integration.spec.ts
+```
+
 ## How to contribute
 
 - Raise an issue in the issue section.

package/lib/bin/cli.cjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+// #!/usr/bin/env node
 "use strict";
 
 Object.defineProperty(exports, "__esModule", {
@@ -8,8 +8,10 @@ exports.Commands = void 0;
 var _args = _interopRequireDefault(require("args"));
 var _nodeProcess = _interopRequireDefault(require("node:process"));
 var _nodeFs = _interopRequireDefault(require("node:fs"));
-var _parseEpub = _interopRequireDefault(require("../parseEpub.cjs"));
-var _convert = require("./convert.cjs");
+var _nodePath = require("node:path");
+var _writeFileSafe = require("write-file-safe");
+var _parseEpub = _interopRequireDefault(require("../epub/parseEpub.cjs"));
+var _convert = require("../convert/convert.cjs");
 var _merge = require("./merge.cjs");
 var _logger = _interopRequireDefault(require("../logger.cjs"));
 var _utils = require("./utils.cjs");
@@ -25,7 +27,7 @@ const Commands = exports.Commands = {
   merge: "merge",
   localize: "localize"
 };
-const commands = [[Commands.convert, "convert the epub file to markdown format"], [Commands.autocorrect, "convert the epub file to markdown format with autocorrect"], [Commands.unzip, "unzip epub file"], [Commands.info, "get epub file basic info"], [Commands.structure, "get epub file structure"], [Commands.sections, "get epub file sections"], [Commands.merge, "merge all markdown files into a single file, can also specify output filename with --merge=filename.md"], [Commands.localize, "Retain the original online link and do not convert it to a local path", false]];
+const commands = [[Commands.convert, "convert the EPUB file to markdown format"], [Commands.autocorrect, "convert the EPUB file to markdown format with autocorrect"], [Commands.unzip, "unzip EPUB file"], [Commands.info, "get EPUB file basic info"], [Commands.structure, "get EPUB file structure"], [Commands.sections, "get EPUB file sections"], [Commands.merge, "Merge all Markdown files into one; specify output filename with --merge=filename.md"], [Commands.localize, 'Download all remotes images to the local "images" folder']];
 const DEFAULT_COMMAND = Commands.convert;
 commands.forEach(cmd => _args.default.option(cmd[0], cmd[1], cmd[2]));
 const flags = _args.default.parse(_nodeProcess.default.argv, {
@@ -52,19 +54,20 @@ for (const cmd of [Commands.info, Commands.structure, Commands.sections]) {
 }
 if (!hasRun && flags[Commands.unzip]) {
   const epubPath = typeof flags[Commands.unzip] === "string" ? flags[Commands.unzip] : unprocessedArgs.length > 0 ? unprocessedArgs[0] : null;
+  const options = {
+    cmd: Commands.unzip,
+    mergedFilename: void 0,
+    shouldMerge: false,
+    localize: false
+  };
   if (epubPath) {
     _logger.default.info("unzipping...");
-    new _convert.Converter(epubPath).run({
-      cmd: Commands.unzip,
-      // Use cmd to indicate unzip only
-      mergedFilename: void 0,
-      shouldMerge: false,
-      localize: false
-    }).then(outDir => {
+    try {
+      const outDir = convert(epubPath, options);
       _logger.default.info(`Unzip successful! output: ${outDir}`);
-    }).catch(error => {
+    } catch (error) {
       _logger.default.error(error);
-    });
+    }
     hasRun = true;
   } else {
     _logger.default.error("No valid epub file path provided for unzip command");
@@ -104,14 +107,14 @@ if (!hasRun) {
 }
 async function run(cmd) {
   if (cmd === Commands.convert || cmd === Commands.autocorrect) {
-    const epubPath = typeof flags[cmd] === "string" ? flags[cmd] : null;
-    if (!epubPath) {
+    const pathArg = typeof flags[cmd] === "string" ? flags[cmd] : null;
+    if (!pathArg) {
       _logger.default.error("No valid epub file path provided");
       return;
     }
-    const epubFiles = await (0, _utils.expandWildcard)(epubPath);
-    if (epubFiles.length === 0) {
-      _logger.default.error(`No files found matching pattern: ${epubPath}`);
+    const epubPaths = await (0, _utils.expandWildcard)(pathArg);
+    if (epubPaths.length === 0) {
+      _logger.default.error(`No files found matching pattern: ${pathArg}`);
       return;
     }
     const shouldMerge = flags.merge === true || typeof flags.merge === "string" && flags.merge !== "";
@@ -119,47 +122,94 @@ async function run(cmd) {
     if (typeof flags.merge === "string" && flags.merge !== "") {
       mergedFilename = flags.merge;
     }
-    if (mergedFilename && epubFiles.length > 1) {
+    if (mergedFilename && epubPaths.length > 1) {
       _logger.default.warn(`Warning: Using custom merge filename "${mergedFilename}" with multiple files. Each file will overwrite the previous merged output.`);
       _logger.default.warn(`Consider using --merge (without filename) to generate separate merged files for each epub.`);
     }
     const localize = flags.localize === true;
-    if (epubFiles.length > 1) {
-      _logger.default.info(`Found ${epubFiles.length} files matching pattern "${epubPath}"`);
+    if (epubPaths.length > 1) {
+      _logger.default.info(`Found ${epubPaths.length} files matching pattern "${pathArg}"`);
     }
-    for (let i = 0; i < epubFiles.length; i++) {
-      const currentFile = epubFiles[i];
-      _logger.default.info(`[${i + 1}/${epubFiles.length}] Converting ${currentFile}${cmd === Commands.autocorrect ? " with autocorrect" : ""}${flags[Commands.merge] ? " and merging" : ""}...`);
+    for (let i = 0; i < epubPaths.length; i++) {
+      const epubPath = epubPaths[i];
+      _logger.default.info(`[${i + 1}/${epubPaths.length}] Converting ${epubPath}${cmd === Commands.autocorrect ? " with autocorrect" : ""}${flags[Commands.merge] ? " and merging" : ""}...`);
+      const options = {
+        cmd,
+        mergedFilename,
+        shouldMerge,
+        localize
+      };
       try {
-        const outDir = await new _convert.Converter(currentFile).run({
-          cmd,
-          mergedFilename,
-          shouldMerge,
-          localize
-        });
+        const outDir = convert(epubPath, options);
         if (shouldMerge) {
-          _logger.default.info(`[${i + 1}/${epubFiles.length}] Merging successful! Output file: ${outDir}`);
+          _logger.default.info(`[${i + 1}/${epubPaths.length}] Merging successful! Output file: ${outDir}`);
         } else {
-          _logger.default.info(`[${i + 1}/${epubFiles.length}] Conversion successful! output: ${outDir}`);
+          _logger.default.info(`[${i + 1}/${epubPaths.length}] Conversion successful! output: ${outDir}`);
         }
       } catch (error) {
-        _logger.default.error(`[${i + 1}/${epubFiles.length}] Failed to convert ${currentFile}:`, error);
+        _logger.default.error(`[${i + 1}/${epubPaths.length}] Failed to convert ${epubPath}:`, error);
       }
     }
-    if (epubFiles.length > 1) {
-      _logger.default.success(`Completed processing ${epubFiles.length} files`);
+    if (epubPaths.length > 1) {
+      _logger.default.success(`Completed processing ${epubPaths.length} files`);
     }
     return;
   }
   const cmdPath = flags[cmd];
   if (typeof cmdPath === "string") {
-    (0, _parseEpub.default)(cmdPath).then(res => {
+    try {
+      const epub = (0, _parseEpub.default)(cmdPath);
+      const data = {
+        info: epub.structure.opf.metadata,
+        structure: epub.structure.toc?.tree,
+        sections: epub.sections
+      }[cmd];
       _logger.default.success(`This book ${cmd}:`);
-      _logger.default.json(res[cmd]);
-    }).catch(error => {
+      _logger.default.json(data);
+    } catch (error) {
       _logger.default.error(error);
-    });
+    }
   } else {
     _logger.default.error(`Path must be a string, got ${typeof cmdPath}`);
   }
 }
+function convert(epubPath, options) {
+  const converter = new _convert.Converter(epubPath, options);
+  if (options?.shouldMerge) return handleMergedFile(converter.mergeProgress);else {
+    handleFiles(converter.files);
+    return converter.outDir;
+  }
+}
+function handleFiles(files) {
+  let markdownFileCount = 0;
+  for (const {
+    type,
+    outputPath,
+    content
+  } of files) {
+    if (type === "md") _logger.default.success(`${++markdownFileCount}: [${(0, _nodePath.basename)(outputPath)}]`);
+    (0, _writeFileSafe.writeFileSync)(outputPath, content, {
+      overwrite: true
+    });
+  }
+}
+function handleMergedFile(mergeFileProcess) {
+  let markdownFileCount = 0;
+  for (const {
+    type,
+    outputPath,
+    content
+  } of mergeFileProcess) {
+    if (type === "markdown file processed") _logger.default.success(`${++markdownFileCount}: [${outputPath}]`);
+    if (type === "file processed") (0, _writeFileSafe.writeFileSync)(outputPath, content, {
+      overwrite: true
+    });
+    if (type === "markdown merged") {
+      (0, _writeFileSafe.writeFileSync)(outputPath, content, {
+        overwrite: true
+      });
+      return outputPath;
+    }
+  }
+  throw "No merged markdown file created";
+}

package/lib/bin/merge.cjs

@@ -47,4 +47,4 @@ async function mergeMarkdowns(directory, outputFile) {
     _logger.default.error(`Failed to merge Markdown files: ${error}`);
     throw error;
   }
-}
+}

package/lib/bin/utils.cjs

@@ -23,4 +23,4 @@ async function expandWildcard(pattern) {
     }
   }
   return [pattern];
-}
+}

package/lib/convert/convert.cjs

@@ -0,0 +1,205 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Converter = void 0;
+var _nodePath = require("node:path");
+var _logger = _interopRequireDefault(require("../logger.cjs"));
+var iteratorHelpersPolyfill = _interopRequireWildcard(require("iterator-helpers-polyfill"));
+var _parseEpub = _interopRequireDefault(require("../epub/parseEpub.cjs"));
+var _helper = require("./helper.cjs");
+var _utils = require("../utils.cjs");
+var _parseLink = _interopRequireDefault(require("../parseLink.cjs"));
+var _downloadImages = require("./download-images.cjs");
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+iteratorHelpersPolyfill.installIntoGlobal();
+const defaultOptions = {
+  cmd: "convert",
+  shouldMerge: false,
+  localize: false
+};
+const IMAGE_DIR = "images";
+class Converter {
+  epub;
+  // epub parser object
+  outDir;
+  // epub 's original directory to save markdown files
+  files;
+  mergeProgress;
+  options;
+  /**
+   * Constructor
+   * @param epubPath - The path to the EPUB file
+   * @param RunOptions - Configuration options or boolean (backward compatibility)
+   */
+  constructor(epubPath, options) {
+    this.options = {
+      ...defaultOptions,
+      ...options
+    };
+    this.epub = (0, _parseEpub.default)(epubPath, {
+      convertToMarkdown: _helper.convertHTML
+    });
+    this.outDir = epubPath.replace(".epub", "");
+    const structures = processManifest(this.epub, this.options.cmd !== "unzip", this.outDir);
+    this.files = structures.values().map(x => this.getFileData(x, structures)).filter(x => x.content.length > 0);
+    if (this.options.shouldMerge) this.mergeProgress = this.mergeFiles();
+  }
+  getFileData(structure, structures) {
+    let {
+      id,
+      type,
+      filepath,
+      outpath
+    } = structure;
+    let content = "";
+    const needAutoCorrect = this.options.cmd === "autocorrect";
+    if (type === "md") {
+      const section = this.epub.getSection(id);
+      if (section) content = section.toMarkdown();
+      const {
+        outPath,
+        fileName
+      } = clearOutpath(structure, this.epub.structure.toc);
+      outpath = outPath;
+      const resLinks = [];
+      const linkStartSep = this.options.shouldMerge ? "#" : "./";
+      content = (0, _helper.fixLinkPath)(content, (link, isText) => {
+        if (isText) {
+          const {
+            hash = "",
+            url
+          } = (0, _parseLink.default)(link, true);
+          if (link.startsWith("#")) return linkStartSep + this.options.shouldMerge ? id : fileName + link;
+          const sectionId = this.epub.structure.opf.manifest.getItemId(url);
+          const internalNavName = this.epub.structure.toc?.getBySectionId(sectionId)?.name || link;
+          let validPath = (0, _helper.sanitizeFileName)((0, _nodePath.extname)(internalNavName) ? internalNavName : internalNavName + ".md");
+          const file = structures.find(file2 => file2.id === sectionId);
+          if (file) validPath = (0, _nodePath.basename)(clearOutpath(file, this.epub.structure.toc).outPath);
+          const toId = this.epub.structure.opf.manifest.getItemId((0, _nodePath.join)((0, _nodePath.dirname)(filepath), url));
+          return this.options.shouldMerge ? linkStartSep + toId + (hash ? "#" + hash : "") : linkStartSep + validPath + `${hash ? "#" + hash : ""}`;
+        } else {
+          if (link.startsWith("http")) {
+            resLinks.push(link);
+          }
+          return "./" + IMAGE_DIR + "/" + (0, _nodePath.basename)(link);
+        }
+      });
+      if (this.options.localize) {
+        try {
+          (0, _downloadImages.downloadRemoteImages)(resLinks, (0, _nodePath.join)(this.outDir, IMAGE_DIR));
+        } catch (error) {
+          _logger.default.error("Failed to localize the image!", error);
+        }
+      } else if (resLinks.length > 0) {
+        _logger.default.warn("Remote images are detected, use --localize to download the images");
+      }
+      content = needAutoCorrect ? require("autocorrect-node").format(content) : content;
+    } else {
+      content = this.epub.getFile(filepath).asNodeBuffer();
+    }
+    return {
+      id,
+      type,
+      content,
+      outputPath: outpath
+    };
+  }
+  *mergeFiles() {
+    const chapters = [];
+    for (const {
+      type,
+      id,
+      outputPath: outputPath2,
+      content
+    } of this.files) if (type === "md") {
+      chapters.push(`<a role="toc_link" id="${id}"></a>
+` + content);
+      yield {
+        type: "markdown file processed",
+        outputPath: (0, _nodePath.basename)(outputPath2)
+      };
+    } else {
+      yield {
+        type: "file processed",
+        outputPath: outputPath2,
+        content
+      };
+    }
+    const outputPath = (0, _nodePath.join)(this.outDir, this.options.mergedFilename || `${(0, _nodePath.basename)(this.outDir)}-merged.md`);
+    yield {
+      type: "markdown merged",
+      outputPath,
+      content: chapters.join("\n\n---\n\n")
+    };
+  }
+}
+exports.Converter = Converter;
+function processManifest(epub, unzip, outDir) {
+  const structure = [];
+  const orderPrefix = new OrderPrefix({
+    maximum: epub.sections.length
+  });
+  for (const {
+    href: filepath,
+    id
+  } of epub.structure.opf.manifest) {
+    if (filepath.endsWith("ncx") || id === "titlepage") continue;
+    const {
+      type,
+      path: outpath
+    } = parseFileInfo(filepath, outDir);
+    if (type === "" && unzip) continue;
+    structure.push({
+      // current only label markdown file
+      orderPrefix: type === "md" ? orderPrefix.next() : "",
+      id,
+      type,
+      outpath,
+      filepath
+    });
+  }
+  return structure;
+}
+class OrderPrefix {
+  count = 0;
+  length;
+  constructor({
+    maximum
+  }) {
+    this.length = Math.floor(Math.log10(maximum)) + 1;
+  }
+  next() {
+    return (++this.count).toString().padStart(this.length, "0");
+  }
+}
+function clearOutpath({
+  id,
+  outpath,
+  orderPrefix
+}, toc) {
+  const nav = toc?.getBySectionId(id);
+  const fileName = (0, _helper.sanitizeFileName)(nav ? nav.name + ".md" : (0, _nodePath.basename)(outpath));
+  const outDir = (0, _nodePath.dirname)(outpath);
+  return {
+    fileName,
+    outDir,
+    outPath: (0, _nodePath.join)(outDir, orderPrefix + "-" + fileName)
+  };
+}
+function parseFileInfo(filepath, outDir) {
+  const {
+    isImage,
+    isHTML
+  } = (0, _helper.checkFileType)(filepath);
+  const name = (0, _nodePath.basename)(filepath);
+  const path = (0, _nodePath.join)(outDir, isImage ? IMAGE_DIR : isHTML ? "" : "static", isHTML ? _utils.Path.fileStem(name) + ".md" : name);
+  return {
+    // html => md
+    type: isHTML ? "md" : isImage ? "img" : "",
+    path
+  };
+}

package/lib/convert/convert.d.ts

@@ -0,0 +1,37 @@
+import { Epub } from '../epub/parseEpub';
+import { type CommandType } from '../bin/cli';
+export interface RunOptions {
+    cmd: CommandType;
+    shouldMerge: boolean;
+    localize: boolean;
+    mergedFilename?: string;
+}
+export declare class Converter {
+    epub: Epub;
+    outDir: string;
+    files: FileData;
+    mergeProgress?: MergeProgress;
+    options: RunOptions;
+    /**
+     * Constructor
+     * @param epubPath - The path to the EPUB file
+     * @param RunOptions - Configuration options or boolean (backward compatibility)
+     */
+    constructor(epubPath: string, options?: Partial<RunOptions>);
+    private getFileData;
+    mergeFiles(): Generator<{
+        readonly type: "markdown file processed";
+        readonly outputPath: string;
+        readonly content?: undefined;
+    } | {
+        readonly type: "file processed";
+        readonly outputPath: any;
+        readonly content: any;
+    } | {
+        readonly type: "markdown merged";
+        readonly outputPath: string;
+        readonly content: string;
+    }, void, unknown>;
+}
+export type FileData = IteratorObject<ReturnType<Converter['getFileData']>>;
+export type MergeProgress = ReturnType<Converter['mergeFiles']>;