@storyteller-platform/epub 0.4.10 → 0.5.0

package/dist/chunk-BIEQXUOY.js

@@ -0,0 +1,50 @@
+var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __using = (stack, value, async) => {
+  if (value != null) {
+    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
+    var dispose, inner;
+    if (async) dispose = value[__knownSymbol("asyncDispose")];
+    if (dispose === void 0) {
+      dispose = value[__knownSymbol("dispose")];
+      if (async) inner = dispose;
+    }
+    if (typeof dispose !== "function") __typeError("Object not disposable");
+    if (inner) dispose = function() {
+      try {
+        inner.call(this);
+      } catch (e) {
+        return Promise.reject(e);
+      }
+    };
+    stack.push([async, dispose, value]);
+  } else if (async) {
+    stack.push([async]);
+  }
+  return value;
+};
+var __callDispose = (stack, error, hasError) => {
+  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
+    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
+  };
+  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
+  var next = (it) => {
+    while (it = stack.pop()) {
+      try {
+        var result = it[1] && it[1].call(it[2]);
+        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
+      } catch (e) {
+        fail(e);
+      }
+    }
+    if (hasError) throw error;
+  };
+  return next();
+};
+
+export {
+  __using,
+  __callDispose
+};

package/dist/index.cjs

@@ -73,7 +73,8 @@ var __callDispose = (stack, error, hasError) => {
 };
 var index_exports = {};
 __export(index_exports, {
-  Epub: () => Epub
+  Epub: () => Epub,
+  EpubVersionError: () => EpubVersionError
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto = require("node:crypto");
@@ -89,6 +90,7 @@ var import_nanoid = require("nanoid");
 var import_yauzl_promise = require("yauzl-promise");
 var import_yazl = require("yazl");
 var import_path = require("@storyteller-platform/path");
+var Upgrade = __toESM(require("./upgrade.ts"), 1);
 const MP3_FILE_EXTENSIONS = [".mp3"];
 const MPEG4_FILE_EXTENSIONS = [".mp4", ".m4a", ".m4b"];
 const AAC_FILE_EXTENSIONS = [".aac"];
@@ -114,6 +116,8 @@ const AUDIO_FILE_EXTENSIONS = [
 function isAudioFile(filenameOrExt) {
   return AUDIO_FILE_EXTENSIONS.some((ext) => filenameOrExt.endsWith(ext));
 }
+class EpubVersionError extends Error {
+}
 class Epub {
   constructor(extractPath, inputPath) {
     this.extractPath = extractPath;
@@ -278,9 +282,29 @@ ${JSON.stringify(element, null, 2)}`
    * the provided name and optional filter.
    */
   static findXmlChildByName(name, xml, filter) {
-    const element = xml.find((e) => name in e && (filter ? filter(e) : true));
+    const element = xml.find(
+      (e) => name in e && (filter ? filter(e) : true)
+    );
     return element;
   }
+  /**
+   * Given an XML structure, find the first descendant matching
+   * the provided name and optional filter.
+   *
+   * Will perform a breadth first search for the element, returning
+   * the highest element in the tree matching the name and filter.
+   */
+  static findXmlDescendantByName(name, xml, filter) {
+    const found = Epub.findXmlChildByName(name, xml, filter);
+    if (found) return found;
+    for (const node of xml) {
+      if (Epub.isXmlTextNode(node)) continue;
+      const children = Epub.getXmlChildren(node);
+      const found2 = this.findXmlDescendantByName(name, children, filter);
+      if (found2) return found2;
+    }
+    return void 0;
+  }
   /**
    * Given an XMLNode, determine whether it represents
    * a text node or an XML element.
@@ -371,9 +395,21 @@ ${JSON.stringify(element, null, 2)}`
    *        path to an EPUB file on disk, or a Uint8Array representing
    *        the data of the EPUB publication.
    */
-  // eslint-disable-next-line @typescript-eslint/require-await
   static async from(pathOrData) {
-    var _a, _b;
+    const epub = await this.open(pathOrData);
+    const version = await epub.getVersion();
+    if (!version.startsWith("3.")) {
+      epub.discardAndClose();
+      throw new EpubVersionError(
+        "This is not a valid EPUB 3 publication. This library only supports EPUB 3, not EPUB 2. Use Epub.upgrade(path) to convert."
+      );
+    }
+    return epub;
+  }
+  /**
+   * Open an EPUB publication and return an Epub instance.
+   */
+  static async open(pathOrData) {
     const extractPath = (0, import_path.join)(
       (0, import_node_os.tmpdir)(),
       `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}.epub`
@@ -416,13 +452,7 @@ ${JSON.stringify(element, null, 2)}`
       epub.discardAndClose();
       console.error(e);
       throw new Error(
-        "This is not a valid EPUB 3 publication. This library only support EPUB 3, not EPUB 2. Try using an automatic conversion tool to convert this publication to EPUB 3."
-      );
-    }
-    const packageEl = await epub.getPackageElement();
-    if (!((_b = (_a = packageEl[":@"]) == null ? void 0 : _a["@_version"]) == null ? void 0 : _b.startsWith("3."))) {
-      throw new Error(
-        "This is not a valid EPUB 3 publication. This library only support EPUB 3, not EPUB 2. Try using an automatic conversion tool to convert this publication to EPUB 3."
+        "This is not a valid EPUB publication. Could not read the package document."
       );
     }
     return epub;
@@ -442,7 +472,7 @@ ${JSON.stringify(element, null, 2)}`
   }
   async removeEntry(href) {
     const rootfile = await this.getRootfile();
-    const filename = this.resolveHref(rootfile, href);
+    const filename = this.resolveInternalHref(rootfile, href);
     await (0, import_promises.rm)(filename);
   }
   async getFileData(path, encoding) {
@@ -815,6 +845,57 @@ ${JSON.stringify(element, null, 2)}`
       value: date.toISOString()
     });
   }
+  /**
+   * Retrieve the modified date from the dcterms:modified metadata
+   * in the EPUB metadata as a Date object.
+   *
+   * If there is no meta element with dcterms:modified, returns null.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-metadata-last-modified
+   */
+  async getModifiedDate() {
+    const metadata = await this.getMetadata();
+    const entry = metadata.find(
+      ({ properties }) => properties["property"] === "dcterms:modified"
+    );
+    if (!(entry == null ? void 0 : entry.value)) return null;
+    return new Date(entry.value);
+  }
+  /**
+   * Retrieve the layout from the rendition:layout meta element
+   * in the EPUB metadata.
+   *
+   * If there is no meta element, returns 'reflowable'.
+   *
+   * @link https://www.w3.org/TR/epub-33/#layout
+   */
+  async getLayout() {
+    const metadata = await this.getMetadata();
+    const entry = metadata.find(
+      ({ properties }) => properties["property"] === "rendition:layout"
+    );
+    if ((entry == null ? void 0 : entry.value) !== "reflowable" && (entry == null ? void 0 : entry.value) !== "pre-paginated") {
+      return "reflowable";
+    }
+    return entry.value;
+  }
+  /**
+   * Retrieve the base direction from the package element.
+   *
+   * If there is no `dir` attribute on the package element,
+   * returns 'auto'.
+   *
+   * @link https://www.w3.org/TR/epub-33/#attrdef-dir
+   */
+  async getBaseDirection() {
+    var _a;
+    const packageEl = await this.getPackageElement();
+    const dir = (_a = packageEl[":@"]) == null ? void 0 : _a["@_dir"];
+    if (dir !== "ltr" && dir !== "rtl" && dir !== "auto") {
+      return "auto";
+    }
+    return dir;
+  }
   /**
    * Set the dc:type metadata element.
    *
@@ -1595,17 +1676,135 @@ ${JSON.stringify(element, null, 2)}`
     });
     this.spine = null;
   }
+  async getNavigationChildren(ol, navHref, { resolveToRoot } = {}) {
+    var _a;
+    const children = [];
+    const childrenElements = Epub.getXmlChildren(ol).filter(
+      (node) => !Epub.isXmlTextNode(node) && Epub.getXmlElementName(node) === "li"
+    );
+    for (const childEl of childrenElements) {
+      const [firstChild, secondChild] = Epub.getXmlChildren(childEl).filter(
+        (node) => !Epub.isXmlTextNode(node) && ["a", "span", "ol"].includes(Epub.getXmlElementName(node))
+      );
+      if (!firstChild) continue;
+      if (!["a", "span"].includes(Epub.getXmlElementName(firstChild))) {
+        continue;
+      }
+      if (Epub.getXmlElementName(firstChild) === "span" && (!secondChild || Epub.getXmlElementName(secondChild) !== "ol")) {
+        continue;
+      }
+      children.push({
+        title: Epub.getXhtmlTextContent(Epub.getXmlChildren(firstChild)),
+        ...Epub.getXmlElementName(firstChild) === "a" && ((_a = firstChild[":@"]) == null ? void 0 : _a["@_href"]) && {
+          href: await this.resolveHref(
+            firstChild[":@"]["@_href"],
+            void 0,
+            { toRoot: resolveToRoot }
+          )
+        },
+        ...secondChild && Epub.getXmlElementName(secondChild) === "ol" && {
+          children: await this.getNavigationChildren(secondChild, navHref, {
+            resolveToRoot
+          })
+        }
+      });
+    }
+    return children;
+  }
+  async getNavigation(role, { resolveToRoot } = {}) {
+    const manifest = await this.getManifest();
+    const navItem = Object.values(manifest).find(
+      (item) => {
+        var _a;
+        return (_a = item.properties) == null ? void 0 : _a.includes("nav");
+      }
+    );
+    if (!navItem) return null;
+    const navContents = await this.readXhtmlItemContents(navItem.id);
+    const navEl = Epub.findXmlDescendantByName(
+      "nav",
+      navContents,
+      (node) => Epub.getXmlAttributes(node)["epub:type"] === role
+    );
+    if (!navEl) return null;
+    const [firstChild, secondChild] = Epub.getXmlChildren(navEl).filter(
+      (node) => !!(!Epub.isXmlTextNode(node) && Epub.getXmlElementName(node).match(/(?:h[1-6]|ol)/))
+    );
+    if (!firstChild) return null;
+    const title = Epub.getXmlElementName(firstChild).match(/h[1-6]/) ? Epub.getXhtmlTextContent(Epub.getXmlChildren(firstChild)) : null;
+    const list = Epub.getXmlElementName(firstChild) === "ol" ? firstChild : secondChild && Epub.getXmlElementName(secondChild) === "ol" ? secondChild : null;
+    if (!list) return null;
+    const children = await this.getNavigationChildren(list, navItem.href, {
+      resolveToRoot
+    });
+    return {
+      ...title && { title },
+      children
+    };
+  }
+  /**
+   * Returns the structured table of contents navigation document
+   * as a Navigation object.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-nav-toc
+   */
+  async getTableOfContents({
+    resolveToRoot
+  } = {}) {
+    const navigationToc = await this.getNavigation("toc", { resolveToRoot });
+    if (navigationToc) return navigationToc;
+    const ncxToc = await this.getNcxTableOfContents();
+    return {
+      children: ncxToc
+    };
+  }
+  /**
+   * Returns the structured landmarks navigation document
+   * as a Navigation object
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-nav-landmarks
+   */
+  async getLandmarks({
+    resolveToRoot
+  } = {}) {
+    return this.getNavigation("landmarks", { resolveToRoot });
+  }
+  /**
+   * Returns the structured page list navigation document
+   * as a Navigation object
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-nav-landmarks
+   */
+  async getPageList({
+    resolveToRoot
+  } = {}) {
+    return this.getNavigation("page-list", { resolveToRoot });
+  }
   /**
    * Returns a Zip Entry path for an HREF
    */
-  resolveHref(from, href) {
+  resolveInternalHref(from, href) {
     const startPath = (0, import_path.dirname)(from);
     return (0, import_path.resolve)(this.extractPath, startPath, href);
   }
+  /**
+   * Returns a path-relative-scheme-less URL, relative to the
+   * container root.
+   *
+   * @param href The href to resolve
+   * @param [relativeTo] Optional - The href to resolve this href relative to.
+       Use if resolving a relative href from a file other than the package document.
+   */
+  async resolveHref(href, relativeTo, { toRoot } = {}) {
+    const rootfile = await this.getRootfile();
+    const from = relativeTo ? this.resolveInternalHref(rootfile, relativeTo) : rootfile;
+    const path = this.resolveInternalHref(from, href);
+    return path.replace(toRoot ? this.extractPath : (0, import_path.dirname)(rootfile), "").slice(1);
+  }
   async readFileContents(href, relativeTo, encoding) {
     const rootfile = await this.getRootfile();
-    const from = relativeTo ? this.resolveHref(rootfile, relativeTo) : rootfile;
-    const path = this.resolveHref(from, href);
+    const from = relativeTo ? this.resolveInternalHref(rootfile, relativeTo) : rootfile;
+    const path = this.resolveInternalHref(from, href);
     const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
     return itemEntry;
   }
@@ -1615,7 +1814,7 @@ ${JSON.stringify(element, null, 2)}`
     const manifestItem = manifest[id];
     if (!manifestItem)
       throw new Error(`Could not find item with id "${id}" in manifest`);
-    const path = this.resolveHref(rootfile, manifestItem.href);
+    const path = this.resolveInternalHref(rootfile, manifestItem.href);
     const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
     return itemEntry;
   }
@@ -1665,7 +1864,7 @@ ${JSON.stringify(element, null, 2)}`
     if (!manifestItem)
       throw new Error(`Could not find item with id "${id}" in manifest`);
     import_mem.default.clear(this.readXhtmlItemContents);
-    const href = this.resolveHref(rootfile, manifestItem.href);
+    const href = this.resolveInternalHref(rootfile, manifestItem.href);
     if (encoding === "utf-8") {
       await this.writeEntryContents(href, contents, encoding);
     } else {
@@ -1740,7 +1939,7 @@ ${JSON.stringify(element, null, 2)}`
     });
     this.manifest = null;
     const rootfile = await this.getRootfile();
-    const filename = this.resolveHref(rootfile, item.href);
+    const filename = this.resolveInternalHref(rootfile, item.href);
     const data = encoding === "utf-8" || encoding === "xml" ? new TextEncoder().encode(
       encoding === "utf-8" ? contents : await Epub.xmlBuilder.build(
         contents
@@ -1897,6 +2096,105 @@ ${JSON.stringify(element, null, 2)}`
       }
     });
   }
+  /**
+   * Returns the EPUB version declared on the package element.
+   */
+  async getVersion() {
+    var _a;
+    const packageElement = await this.getPackageElement();
+    return ((_a = packageElement[":@"]) == null ? void 0 : _a["@_version"]) ?? "2.0";
+  }
+  /**
+   * Parse the NCX table of contents, if one exists, and return
+   * a tree of TocEntry nodes.
+   *
+   * Useful for both EPUB 2 publications (where the NCX is the
+   * primary navigation) and EPUB 3 publications that retain an
+   * NCX for backwards compatibility.
+   */
+  async getNcxTableOfContents() {
+    var _a;
+    const [manifest, packageElement] = await Promise.all([
+      this.getManifest(),
+      this.getPackageElement()
+    ]);
+    const spine = Epub.findXmlChildByName(
+      "spine",
+      Epub.getXmlChildren(packageElement)
+    );
+    const spineTocId = (_a = spine == null ? void 0 : spine[":@"]) == null ? void 0 : _a["@_toc"];
+    const ncxItem = spineTocId ? manifest[spineTocId] : Object.values(manifest).find(
+      (item) => {
+        var _a2;
+        return ((_a2 = item.mediaType) == null ? void 0 : _a2.toLowerCase()) === "application/x-dtbncx+xml";
+      }
+    );
+    if (!ncxItem) return [];
+    const ncxContent = await this.readItemContents(ncxItem.id, "utf-8");
+    const ncxXml = Epub.xmlParser.parse(ncxContent);
+    const ncxElement = Epub.findXmlChildByName("ncx", ncxXml);
+    if (!ncxElement) return [];
+    const ncxChildren = Epub.getXmlChildren(ncxElement);
+    const navMap = Epub.findXmlChildByName("navMap", ncxChildren) ?? Epub.findXmlChildByName("navmap", ncxChildren);
+    if (!navMap) return [];
+    return this.parseNavPoints(Epub.getXmlChildren(navMap), ncxItem.href);
+  }
+  async parseNavPoints(nodes, ncxHref) {
+    var _a;
+    const entries = [];
+    for (const node of nodes) {
+      if (Epub.isXmlTextNode(node)) continue;
+      const name = Epub.getXmlElementName(node);
+      const isNavPoint = name === "navPoint" || name === "navpoint";
+      if (!isNavPoint) continue;
+      const children = Epub.getXmlChildren(node);
+      const navLabel = Epub.findXmlChildByName("navLabel", children) ?? Epub.findXmlChildByName("navlabel", children);
+      let title = null;
+      if (navLabel) {
+        const textEl = Epub.findXmlChildByName(
+          "text",
+          Epub.getXmlChildren(navLabel)
+        );
+        if (textEl) {
+          title = Epub.getXhtmlTextContent(Epub.getXmlChildren(textEl)).trim() || null;
+        }
+      }
+      const contentEl = Epub.findXmlChildByName("content", children);
+      const src = (_a = contentEl == null ? void 0 : contentEl[":@"]) == null ? void 0 : _a["@_src"];
+      const href = src ? await this.resolveHref(src, ncxHref) : null;
+      const childEntries = await this.parseNavPoints(children, ncxHref);
+      entries.push({
+        title: title ?? `${entries.length}`,
+        ...href && { href },
+        children: childEntries
+      });
+    }
+    return entries;
+  }
+  /**
+   * Retrieve the guide entries from the package document.
+   *
+   * The guide element is deprecated in EPUB 3 in favor of
+   * the landmarks nav, but many publications still include it.
+   */
+  async getGuideEntries() {
+    const packageElement = await this.getPackageElement();
+    const guide = Epub.findXmlChildByName(
+      "guide",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!guide) return [];
+    return Epub.getXmlChildren(guide).filter(
+      (node) => !Epub.isXmlTextNode(node) && "reference" in node
+    ).map((ref) => {
+      var _a, _b, _c;
+      return {
+        href: ((_a = ref[":@"]) == null ? void 0 : _a["@_href"]) ?? "",
+        title: ((_b = ref[":@"]) == null ? void 0 : _b["@_title"]) ?? "",
+        type: (((_c = ref[":@"]) == null ? void 0 : _c["@_type"]) ?? "").toLowerCase()
+      };
+    }).filter((entry) => entry.href);
+  }
   discardAndClose() {
     this.rootfile = null;
     this.manifest = null;
@@ -1967,11 +2265,76 @@ ${JSON.stringify(element, null, 2)}`
       _promise && await _promise;
     }
   }
+  /**
+   * Upgrade an EPUB 2 publication to EPUB 3 in place, returning a new, valid Epub 3 instance.
+   *
+   * Performs the following transformations:
+   *  - upgrades OPF metadata to EPUB 3 conventions
+   *  - scans XHTML documents and adds manifest item properties
+   *  - parses the NCX into a TOC tree and generates a nav.xhtml
+   *  - removes the NCX file and the guide element (configurable)
+   *  - fixes common font MIME types
+   *  - bumps the package version to 3.0
+   *  - goes over each xhtml item and rewrites it using XMLParser to make sure the output is valid XHTML
+   */
+  static async upgrade(path, options = {}) {
+    var _a;
+    const { removeNcx = false, outputPath } = options;
+    if (outputPath) {
+      await (0, import_promises.mkdir)((0, import_path.dirname)(outputPath), { recursive: true });
+      await (0, import_promises.cp)(path, outputPath, { force: true });
+    }
+    const epub = await Epub.open(outputPath ?? path);
+    const version = await epub.getVersion();
+    if (version.startsWith("3.")) {
+      return epub;
+    }
+    const tocEntries = await epub.getNcxTableOfContents();
+    let landmarks = [];
+    await epub.withPackage((pkg) => {
+      landmarks = Upgrade.extractGuideLandmarks(pkg);
+      Upgrade.upgradePackageMetadata(pkg);
+      Upgrade.fixFontMimeTypes(pkg);
+      Upgrade.removeGuide(pkg);
+      if (removeNcx) {
+        Upgrade.removeSpineTocRef(pkg);
+      }
+      Upgrade.setPackageVersion(pkg, "3.0");
+    });
+    await Upgrade.collectManifestProperties(epub);
+    if (removeNcx) {
+      await Upgrade.removeNcx(epub);
+    }
+    const navHref = await Upgrade.chooseNavHref(epub);
+    const navContent = await Upgrade.buildNavDocument(
+      epub,
+      tocEntries,
+      landmarks
+    );
+    await epub.addManifestItem(
+      {
+        id: "nav",
+        href: navHref,
+        mediaType: "application/xhtml+xml",
+        properties: ["nav"]
+      },
+      navContent,
+      "utf-8"
+    );
+    const manifest = await epub.getManifest();
+    for (const item of Object.values(manifest)) {
+      if (((_a = item.mediaType) == null ? void 0 : _a.toLowerCase()) !== "application/xhtml+xml") continue;
+      const contents = await epub.readXhtmlItemContents(item.id);
+      await epub.writeXhtmlItemContents(item.id, contents);
+    }
+    return epub;
+  }
   [Symbol.dispose]() {
     this.discardAndClose();
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Epub
+  Epub,
+  EpubVersionError
 });