@storyteller-platform/epub 0.6.3 → 0.7.1

package/dist/index.cjs

@@ -40,8 +40,8 @@ var import_promises = require("node:fs/promises");
 var import_async_mutex = require("async-mutex");
 var import_fast_xml_parser = require("fast-xml-parser");
 var import_mem = __toESM(require("mem"), 1);
-var import_mime_types = require("mime-types");
 var import_nanoid = require("nanoid");
+var import_media_types = require("@storyteller-platform/media-types");
 var import_path = require("@storyteller-platform/path");
 var import_tmpfs = require("./adapters/tmpfs.cjs");
 var Upgrade = __toESM(require("./upgrade.ts"), 1);
@@ -51,6 +51,61 @@ class EpubVersionError extends Error {
 }
 class EpubReadOnlyError extends Error {
 }
+const OPF_NAMESPACE = "http://www.idpf.org/2007/opf";
+const ENTRY_ORIGIN = "epub:///";
+function entryToUrlPath(entry) {
+  return entry.split("/").map(encodeURIComponent).join("/");
+}
+function resolveEntryUrl(from, href) {
+  const base = new URL(entryToUrlPath(from), ENTRY_ORIGIN);
+  if (!URL.canParse(href, base.toString())) return null;
+  const url = new URL(href, base);
+  return url.href.startsWith(ENTRY_ORIGIN) ? url : null;
+}
+function renameOpfAttributes(attrs, prefix) {
+  const attrPrefix = `@_${prefix}:`;
+  const renamed = {};
+  for (const [key, value] of Object.entries(attrs)) {
+    if (key === `@_xmlns:${prefix}`) continue;
+    if (key.startsWith(attrPrefix)) {
+      renamed[`@_opf:${key.slice(attrPrefix.length)}`] = value;
+    } else {
+      renamed[key] = value;
+    }
+  }
+  return renamed;
+}
+function stripOpfPrefix(node, prefix) {
+  if (Epub.isXmlTextNode(node)) return node;
+  const name = Epub.getXmlElementName(node);
+  const bareName = name.startsWith(`${prefix}:`) ? name.slice(prefix.length + 1) : name;
+  const element = {
+    [bareName]: Epub.getXmlChildren(node).map(
+      (child) => stripOpfPrefix(child, prefix)
+    )
+  };
+  if (node[":@"]) {
+    element[":@"] = renameOpfAttributes(node[":@"], prefix);
+  }
+  return element;
+}
+function normalizeOpfNamespacePrefixes(doc) {
+  var _a;
+  const root = doc.find(
+    (node) => !Epub.isXmlTextNode(node) && Epub.getXmlElementName(node).endsWith(":package")
+  );
+  if (!root) return doc;
+  const prefix = Epub.getXmlElementName(root).slice(0, -":package".length);
+  if (((_a = root[":@"]) == null ? void 0 : _a[`@_xmlns:${prefix}`]) !== OPF_NAMESPACE) return doc;
+  const stripped = stripOpfPrefix(root, prefix);
+  stripped[":@"] = {
+    ...stripped[":@"],
+    "@_xmlns": OPF_NAMESPACE,
+    "@_xmlns:opf": OPF_NAMESPACE
+  };
+  doc[doc.indexOf(root)] = stripped;
+  return doc;
+}
 class Epub {
   /**
    * Prefer the static factories ({@link Epub.using}, {@link Epub.from},
@@ -331,14 +386,7 @@ ${JSON.stringify(element, null, 2)}`
       );
     }
     const rootfile = await this.getRootfile();
-    const filename = this.resolveInternalHref(rootfile, href);
-    await this.adapter.remove(filename);
-  }
-  async getFileData(path, encoding) {
-    if (encoding) {
-      return this.adapter.read(path, encoding);
-    }
-    return this.adapter.read(path);
+    await this.adapter.remove(await this.resolveEntry(rootfile, href));
   }
   /**
    * Length of the underlying archive entry for a manifest item, in bytes
@@ -351,14 +399,15 @@ ${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.resolveInternalHref(rootfile, manifestItem.href);
-    return this.adapter.archiveLength(path);
+    return this.adapter.archiveLength(
+      await this.resolveEntry(rootfile, manifestItem.href)
+    );
   }
   async getRootfile() {
     var _a;
     if (this.rootfile !== null) return this.rootfile;
-    const containerString = await this.getFileData(
-      (0, import_path.join)(this.adapter.rootPath, "META-INF", "container.xml"),
+    const containerString = await this.adapter.read(
+      "META-INF/container.xml",
       "utf-8"
     );
     if (!containerString)
@@ -382,7 +431,7 @@ ${JSON.stringify(element, null, 2)}`
       Epub.getXmlChildren(rootfiles),
       (node) => {
         var _a2;
-        return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_media-type"]) === "application/oebps-package+xml";
+        return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_media-type"]) === import_media_types.MediaType.OPF.mime;
       }
     );
     const fullPath = (_a = rootfile == null ? void 0 : rootfile[":@"]) == null ? void 0 : _a["@_full-path"];
@@ -390,12 +439,12 @@ ${JSON.stringify(element, null, 2)}`
       throw new Error(
         "Failed to parse EPUB container.xml: Found no rootfile element"
       );
-    this.rootfile = (0, import_path.resolve)(this.adapter.rootPath, fullPath);
+    this.rootfile = await this.resolveEntry("", fullPath);
     return this.rootfile;
   }
   async getPackageDocument() {
     const rootfile = await this.getRootfile();
-    const packageDocumentString = await this.getFileData(rootfile, "utf-8");
+    const packageDocumentString = await this.adapter.read(rootfile, "utf-8");
     if (!packageDocumentString)
       throw new Error(
         `Failed to parse EPUB: could not find package document at ${rootfile}`
@@ -403,7 +452,7 @@ ${JSON.stringify(element, null, 2)}`
     const packageDocument = Epub.xmlParser.parse(
       packageDocumentString
     );
-    return packageDocument;
+    return normalizeOpfNamespacePrefixes(packageDocument);
   }
   async getPackageElement() {
     const packageDocument = await this.getPackageDocument();
@@ -582,12 +631,15 @@ ${JSON.stringify(element, null, 2)}`
     return metadata;
   }
   /**
-   * Retrieve the identifier from the dc:identifier element
+   * Retrieve the first identifier from the dc:identifier element
    * in the EPUB metadata.
    *
    * If there is no dc:identifier element, returns null.
    *
    * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   *
+   * @deprecated Use {@link getUniqueIdentifier} instead to get the unique identifier,
+   * or {@link getIdentifiers} to get all identifiers.
    */
   async getIdentifier() {
     const metadata = await this.getMetadata();
@@ -601,6 +653,8 @@ ${JSON.stringify(element, null, 2)}`
    * Otherwise creates a new element
    *
    * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   *
+   * @deprecated Use {@link setUniqueIdentifier} instead.
    */
   async setIdentifier(identifier) {
     await this.replaceMetadata(({ type }) => type === "dc:identifier", {
@@ -609,6 +663,395 @@ ${JSON.stringify(element, null, 2)}`
       value: identifier
     });
   }
+  /**
+   * Retrieve the identifier with the unique identifier id
+   * in the EPUB metadata.
+   *
+   * If there is no unique identifier id, returns the first dc:identifier element.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getUniqueIdentifier() {
+    const metadata = await this.getMetadata();
+    const uniqueId = await this.getUniqueIdentifierId();
+    if (!uniqueId) {
+      return null;
+    }
+    const entry = metadata.find(
+      ({ type, id }) => type === "dc:identifier" && id === uniqueId
+    );
+    return (entry == null ? void 0 : entry.value) ?? null;
+  }
+  /**
+   * Set the unique identifier id for the EPUB.
+   *
+   * Updates the existing dc:identifier element referenced by the unique identifier id if one exists.
+   * Otherwise creates a new element with the provided identifier, and sets the unique identifier id to the new element's id.
+   *
+   * Note: you likely shouldn't change the unique identifier id unless you are producing a new EPUB.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async setUniqueIdentifier(identifier) {
+    await this.withPackage(async (packageElement) => {
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata) {
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      }
+      let uniqueId = await this.getUniqueIdentifierId();
+      if (!uniqueId) {
+        const newUniqueId = (0, import_nanoid.nanoid)();
+        packageElement[":@"] = {
+          ...packageElement[":@"],
+          "@_unique-identifier": newUniqueId
+        };
+        uniqueId = newUniqueId;
+      }
+      const children = Epub.getXmlChildren(metadata);
+      const entry = Epub.findXmlChildByName(
+        "dc:identifier",
+        children,
+        (node) => {
+          var _a;
+          return ((_a = node[":@"]) == null ? void 0 : _a["@_id"]) === uniqueId;
+        }
+      );
+      if (entry) {
+        children.splice(
+          children.indexOf(entry),
+          1,
+          Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
+            Epub.createXmlTextNode(identifier)
+          ])
+        );
+        return;
+      }
+      children.push(
+        Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
+          Epub.createXmlTextNode(identifier)
+        ])
+      );
+    });
+  }
+  /**
+   * Retrieve the id of the publication's unique identifier, as declared by the
+   * package element's `unique-identifier` attribute.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getUniqueIdentifierId() {
+    var _a;
+    const packageElement = await this.getPackageElement();
+    return ((_a = packageElement[":@"]) == null ? void 0 : _a["@_unique-identifier"]) ?? null;
+  }
+  /**
+   * Collect `dc:identifier` or `dc:source` entries, attaching the value and
+   * scheme of any refining `identifier-type` meta (spec D.3.8) and a legacy
+   * `opf:scheme` attribute. Values are not interpreted.
+   *
+   * `onRefinement` is invoked for every other meta refining a collected entry,
+   * so callers can surface element-specific refinements (e.g. `source-of` on a
+   * `dc:source`).
+   */
+  static collectDcEntries(metadata, type, onRefinement) {
+    const entries = metadata.filter((entry) => entry.type === type && entry.value !== void 0).map((entry) => ({
+      // filtered above, so value is defined
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      value: entry.value,
+      ...entry.id && { id: entry.id },
+      ...entry.properties["opf:scheme"] && {
+        scheme: entry.properties["opf:scheme"]
+      }
+    }));
+    for (const meta of metadata) {
+      if (meta.type !== "meta" || meta.value === void 0) continue;
+      const property = meta.properties["property"];
+      const refines = meta.properties["refines"];
+      if (!property || !refines) continue;
+      const target = entries.find((t) => t.id === refines.slice(1));
+      if (!target) continue;
+      if (property === "identifier-type") {
+        target.identifierType = meta.value;
+        if (meta.properties["scheme"]) target.scheme = meta.properties["scheme"];
+      } else {
+        onRefinement == null ? void 0 : onRefinement(target, property, meta.value);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Retrieve every `dc:identifier` entry, returned as found.
+   *
+   * Values are not interpreted. Any refining `identifier-type` meta (spec
+   * D.3.8) or legacy `opf:scheme` attribute is surfaced on the entry, but no
+   * parsing of the value itself is attempted. To read `dc:source` entries, use
+   * {@link getSources}.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getIdentifiers() {
+    const metadata = await this.getMetadata();
+    return Epub.collectDcEntries(metadata, "dc:identifier");
+  }
+  /**
+   * Retrieve every `dc:source` entry, returned as found.
+   *
+   * Like {@link getIdentifiers}, values are not interpreted. In addition to a
+   * refining `identifier-type`, a refining `source-of` meta (spec D.3.11) is
+   * surfaced as `sourceOf`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+   */
+  async getSources() {
+    const metadata = await this.getMetadata();
+    return Epub.collectDcEntries(
+      metadata,
+      "dc:source",
+      (source, property) => {
+        if (property === "source-of") {
+          source.isPageBreakSource = true;
+        }
+      }
+    );
+  }
+  /**
+   * Retrieve the `pageBreakSource` property (EPUB 3.4, spec D.2.9), the
+   * publication-level source for the source of its page break markers.
+   *
+   * This property replaces the refining `source-of="pagination"` meta (spec
+   * D.3.11), see {@link EpubSource.sourceOf}. If no `pageBreakSource` property is found,
+   * we fall back to finding a `dc:source` with a `source-of="pagination"` refinement.
+   *
+   * @link https://www.w3.org/TR/epub/#pageBreakSource
+   */
+  async getPageBreakSource() {
+    const entry = await this.findMetadataItem(
+      (item) => item.type === "meta" && item.properties["property"] === "pageBreakSource" && !!item.value
+    );
+    if (entry) {
+      return {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        value: entry.value,
+        id: entry.id,
+        identifierType: void 0,
+        scheme: void 0,
+        isPageBreakSource: true
+      };
+    }
+    const sources = await this.getSources();
+    const source = sources.find((source2) => source2.isPageBreakSource);
+    if (source) {
+      return source;
+    }
+    return null;
+  }
+  /**
+   * Set the `pageBreakSource` property (EPUB 3.4, spec D.2.9), or remove it when
+   * passed null. Replaces an existing `pageBreakSource` meta if present.
+   *
+   * Pass `none` to indicate the pagination is unique to this publication.
+   *
+   * @link https://www.w3.org/TR/epub/#pageBreakSource
+   */
+  async setPageBreakSource(value) {
+    if (value === null) {
+      await this.removeMetadata(
+        (item) => item.properties["property"] === "pageBreakSource"
+      );
+      return;
+    }
+    await this.replaceMetadata(
+      (item) => item.properties["property"] === "pageBreakSource",
+      { type: "meta", properties: { property: "pageBreakSource" }, value }
+    );
+  }
+  /**
+   * Replace the publication's `dc:identifier` entries.
+   *
+   * This replaces ALL existing `dc:identifier` elements except the publication's
+   * unique identifier (the one referenced by the package element's
+   * `unique-identifier` attribute), which is always preserved and must not be
+   * included in the provided list. If included anyway, it is ignored. See
+   * {@link setUniqueIdentifier} to change it.
+   *
+   * Identifiers are placed in the order they are provided.
+   *
+   * `dc:source` entries are not touched, use {@link setSources} for those.
+   *
+   * When an entry has an `identifierType`, it is written in the refining form
+   * (a `meta` with `property="identifier-type"`, carrying the `scheme`
+   * attribute when provided). An entry with only a `scheme` is written using
+   * the legacy `opf:scheme` attribute.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async setIdentifiers(identifiers) {
+    const uniqueId = await this.getUniqueIdentifierId();
+    await this.withPackage((packageElement) => {
+      var _a;
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const children = Epub.getXmlChildren(metadata);
+      const removedIds = /* @__PURE__ */ new Set();
+      for (let i = children.length - 1; i >= 0; i--) {
+        const node = children[i];
+        if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "dc:identifier") {
+          continue;
+        }
+        const id = (_a = node[":@"]) == null ? void 0 : _a["@_id"];
+        if (id && id === uniqueId) {
+          continue;
+        }
+        if (id) {
+          removedIds.add(id);
+        }
+        children.splice(i, 1);
+      }
+      Epub.removeRefiningMetas(children, removedIds, ["identifier-type"]);
+      for (const identifier of identifiers) {
+        if (identifier.id && identifier.id === uniqueId) continue;
+        const id = identifier.id ?? (identifier.identifierType !== void 0 ? (0, import_nanoid.nanoid)() : void 0);
+        children.push(
+          Epub.createXmlElement(
+            "dc:identifier",
+            {
+              ...id && { id },
+              ...identifier.scheme && identifier.identifierType === void 0 && {
+                "opf:scheme": identifier.scheme
+              }
+            },
+            [Epub.createXmlTextNode(identifier.value)]
+          )
+        );
+        if (identifier.identifierType !== void 0 && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              {
+                refines: `#${id}`,
+                property: "identifier-type",
+                ...identifier.scheme && { scheme: identifier.scheme }
+              },
+              [Epub.createXmlTextNode(identifier.identifierType)]
+            )
+          );
+        }
+      }
+    });
+  }
+  /**
+   * Remove `meta` refinements pointing at any of the given ids,
+   * restricted to the given `property` values as a cleanup step
+   * Mutates `children` in place.
+   */
+  static removeRefiningMetas(children, ids, properties) {
+    var _a, _b, _c;
+    for (let i = children.length - 1; i >= 0; i--) {
+      const node = children[i];
+      if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "meta") {
+        continue;
+      }
+      const property = (_a = node[":@"]) == null ? void 0 : _a["@_property"];
+      if (!property || !properties.includes(property)) continue;
+      const refines = (_c = (_b = node[":@"]) == null ? void 0 : _b["@_refines"]) == null ? void 0 : _c.slice(1);
+      if (refines && ids.has(refines)) {
+        children.splice(i, 1);
+      }
+    }
+  }
+  /**
+   * Replace the publication's `dc:source` entries.
+   *
+   * This replaces ALL existing `dc:source` elements (and their refining
+   * `identifier-type` / `source-of` metas). `dc:identifier` entries are not
+   * touched; use {@link setIdentifiers} for those. Pass an empty array to
+   * remove all sources.
+   *
+   * When an entry has an `identifierType`, it is written in the refining form.
+   * A `sourceOf` value is written as a refining `source-of` meta (spec D.3.11).
+   * An entry with only a `scheme` uses the legacy `opf:scheme` attribute.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+   */
+  async setSources(sources) {
+    await this.withPackage((packageElement) => {
+      var _a;
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const children = Epub.getXmlChildren(metadata);
+      const removedIds = /* @__PURE__ */ new Set();
+      for (let i = children.length - 1; i >= 0; i--) {
+        const node = children[i];
+        if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "dc:source") {
+          continue;
+        }
+        const id = (_a = node[":@"]) == null ? void 0 : _a["@_id"];
+        if (id) {
+          removedIds.add(id);
+        }
+        children.splice(i, 1);
+      }
+      Epub.removeRefiningMetas(children, removedIds, [
+        "identifier-type",
+        "source-of"
+      ]);
+      for (const source of sources) {
+        const needsId = source.identifierType !== void 0 || source.isPageBreakSource;
+        const id = source.id ?? (needsId ? (0, import_nanoid.nanoid)() : void 0);
+        children.push(
+          Epub.createXmlElement(
+            "dc:source",
+            {
+              ...id && { id },
+              ...source.scheme && source.identifierType === void 0 && {
+                "opf:scheme": source.scheme
+              }
+            },
+            [Epub.createXmlTextNode(source.value)]
+          )
+        );
+        if (source.identifierType !== void 0 && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              {
+                refines: `#${id}`,
+                property: "identifier-type",
+                ...source.scheme && { scheme: source.scheme }
+              },
+              [Epub.createXmlTextNode(source.identifierType)]
+            )
+          );
+        }
+        if (source.isPageBreakSource && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              { refines: `#${id}`, property: "source-of" },
+              [Epub.createXmlTextNode("pagination")]
+            )
+          );
+        }
+      }
+    });
+  }
   /**
    * Even "EPUB 3" publications sometimes still only use the
    * EPUB 2 specification for identifying the cover image.
@@ -681,11 +1124,12 @@ ${JSON.stringify(element, null, 2)}`
    * the provided href within the publication.
    */
   async setCoverImage(href, data) {
+    var _a;
     const coverImageItem = await this.getCoverImageItem();
     if (coverImageItem) {
       await this.removeManifestItem(coverImageItem.id);
     }
-    const mediaType = (0, import_mime_types.lookup)(href);
+    const mediaType = (_a = import_media_types.MediaType.fromPath(href)) == null ? void 0 : _a.mime;
     if (!mediaType)
       throw new Error(`Invalid file extension for cover image: ${href}`);
     await this.addManifestItem(
@@ -1664,35 +2108,81 @@ ${JSON.stringify(element, null, 2)}`
     return this.getNavigation("page-list", { resolveToRoot });
   }
   /**
-   * Returns a Zip Entry path for an HREF
+   * Name the entry a resolved URL addresses.
+   *
+   * A correctly authored publication percent-encodes its hrefs, so the
+   * decoded reading is the one the spec calls for and the one we prefer.
+   * Some publications instead write the entry name verbatim, so when the two
+   * readings differ we ask the archive which one it holds. A verbatim name
+   * carrying a bare `%`, as `100%.xhtml` does, is not a valid encoding at all
+   * and can only be its own answer.
    */
-  resolveInternalHref(from, href) {
-    const startPath = (0, import_path.dirname)(from);
-    return (0, import_path.resolve)(
-      this.adapter.rootPath,
-      (0, import_path.hrefToPlatformPath)(startPath),
-      (0, import_path.hrefToPlatformPath)(href)
-    );
+  async entryForUrl(url) {
+    const asWritten = url.pathname.slice(1);
+    let decoded;
+    try {
+      decoded = decodeURIComponent(asWritten);
+    } catch {
+      return asWritten;
+    }
+    if (decoded === asWritten) {
+      return decoded;
+    }
+    if (await this.adapter.exists(decoded)) {
+      return decoded;
+    }
+    return await this.adapter.exists(asWritten) ? asWritten : decoded;
+  }
+  /**
+   * Resolve an href to the name of the archive entry it addresses.
+   *
+   * @param from The entry the href appears in; it resolves against that
+   *   entry's directory
+   * @throws when the href addresses something outside the publication
+   */
+  async resolveEntry(from, href) {
+    const url = resolveEntryUrl(from, href);
+    if (!url) {
+      throw new Error(
+        `href does not address an entry in this publication: ${href}`
+      );
+    }
+    return this.entryForUrl(url);
   }
   /**
    * Returns a path-relative-scheme-less URL, relative to the
    * container root.
    *
+   * An href that points outside the publication, such as an external link in
+   * a navigation document, is handed back unchanged.
+   *
    * @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 } = {}) {
+    if (href.startsWith("#")) return href;
     const rootfile = await this.getRootfile();
-    const from = relativeTo ? this.resolveInternalHref(rootfile, relativeTo) : rootfile;
-    const path = this.resolveInternalHref(from, href);
-    return path.replace(toRoot ? this.adapter.rootPath : (0, import_path.dirname)(rootfile), "").slice(1);
+    const from = relativeTo ? await this.resolveEntry(rootfile, relativeTo) : rootfile;
+    const url = resolveEntryUrl(from, href);
+    if (!url) return href;
+    const entry = (await this.entryForUrl(url)).split("/");
+    const base = toRoot ? [] : rootfile.split("/").slice(0, -1);
+    let shared = 0;
+    while (shared < base.length && base[shared] === entry[shared]) {
+      shared++;
+    }
+    const relative = [
+      ...Array(base.length - shared).fill(".."),
+      ...entry.slice(shared).map(encodeURIComponent)
+    ];
+    return relative.join("/") + url.hash;
   }
   async readFileContents(href, relativeTo, encoding) {
     const rootfile = await this.getRootfile();
-    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);
+    const from = relativeTo ? await this.resolveEntry(rootfile, relativeTo) : rootfile;
+    const entry = await this.resolveEntry(from, href);
+    const itemEntry = encoding ? await this.adapter.read(entry, encoding) : await this.adapter.read(entry);
     return itemEntry;
   }
   async readItemContents(id, encoding) {
@@ -1701,8 +2191,8 @@ ${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.resolveInternalHref(rootfile, manifestItem.href);
-    const itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
+    const entry = await this.resolveEntry(rootfile, manifestItem.href);
+    const itemEntry = encoding ? await this.adapter.read(entry, encoding) : await this.adapter.read(entry);
     return itemEntry;
   }
   /**
@@ -1760,11 +2250,11 @@ ${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.resolveInternalHref(rootfile, manifestItem.href);
+    const entry = await this.resolveEntry(rootfile, manifestItem.href);
     if (encoding === "utf-8") {
-      await this.writeEntryContents(href, contents, encoding);
+      await this.writeEntryContents(entry, contents, encoding);
     } else {
-      await this.writeEntryContents(href, contents);
+      await this.writeEntryContents(entry, contents);
     }
   }
   /**
@@ -1835,7 +2325,7 @@ ${JSON.stringify(element, null, 2)}`
     });
     this.manifest = null;
     const rootfile = await this.getRootfile();
-    const filename = this.resolveInternalHref(rootfile, item.href);
+    const filename = await this.resolveEntry(rootfile, item.href);
     const data = encoding === "utf-8" || encoding === "xml" ? new TextEncoder().encode(
       encoding === "utf-8" ? contents : await Epub.xmlBuilder.build(
         contents
@@ -2019,10 +2509,7 @@ ${JSON.stringify(element, null, 2)}`
     );
     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";
-      }
+      (item) => import_media_types.MediaType.fromMime(item.mediaType ?? "") === import_media_types.MediaType.NCX
     );
     if (!ncxItem) return [];
     const ncxContent = await this.readItemContents(ncxItem.id, "utf-8");
@@ -2163,7 +2650,12 @@ class EpubFactory {
         "This is not a valid EPUB publication. Could not read the package document."
       );
     }
-    await Epub.assertEpub3(epub);
+    try {
+      await Epub.assertEpub3(epub);
+    } catch (error) {
+      epub.discardAndClose();
+      throw error;
+    }
     return epub;
   }
   /**
@@ -2203,14 +2695,11 @@ class EpubFactory {
     const container = encoder.encode(`<?xml version="1.0"?>
 <container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
   <rootfiles>
-    <rootfile media-type="application/oebps-package+xml" full-path="OEBPS/content.opf"/>
+    <rootfile media-type="${import_media_types.MediaType.OPF.mime}" full-path="OEBPS/content.opf"/>
   </rootfiles>
 </container>
 `);
-    await adapter.write(
-      (0, import_path.join)(adapter.rootPath, "META-INF", "container.xml"),
-      container
-    );
+    await adapter.write("META-INF/container.xml", container);
     const packageDocument = encoder.encode(`<?xml version="1.0"?>
 <package unique-identifier="pub-id" dir="${language.textInfo.direction}" xml:lang="${language.toString()}" version="3.0" xmlns:dc="http://purl.org/dc/elements/1.1/">
   <metadata>
@@ -2221,10 +2710,7 @@ class EpubFactory {
   </spine>
 </package>
 `);
-    await adapter.write(
-      (0, import_path.join)(adapter.rootPath, "OEBPS", "content.opf"),
-      packageDocument
-    );
+    await adapter.write("OEBPS/content.opf", packageDocument);
     const epub = new Epub(this.adapterClass, adapter, path);
     const metadata = [
       {
@@ -2273,7 +2759,6 @@ class EpubFactory {
    * @throws when the adapter is read-only
    */
   async upgrade(path, options = {}) {
-    var _a;
     if (!this.adapterClass.capabilities.writable) {
       throw new EpubReadOnlyError(
         `adapter ${this.adapterClass.kind} is read-only; cannot upgrade`
@@ -2299,49 +2784,55 @@ class EpubFactory {
         "This is not a valid EPUB publication. Could not read the package document."
       );
     }
-    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);
+    try {
+      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) {
-        Upgrade.removeSpineTocRef(pkg);
+        await Upgrade.removeNcx(epub);
       }
-      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);
+      const navHref = await Upgrade.chooseNavHref(epub);
+      const navContent = await Upgrade.buildNavDocument(
+        epub,
+        tocEntries,
+        landmarks
+      );
+      await epub.addManifestItem(
+        {
+          id: "nav",
+          href: navHref,
+          mediaType: import_media_types.MediaType.XHTML.mime,
+          properties: ["nav"]
+        },
+        navContent,
+        "utf-8"
+      );
+      const manifest = await epub.getManifest();
+      for (const item of Object.values(manifest)) {
+        if (import_media_types.MediaType.fromMime(item.mediaType ?? "") !== import_media_types.MediaType.XHTML)
+          continue;
+        const contents = await epub.readXhtmlItemContents(item.id);
+        await epub.writeXhtmlItemContents(item.id, contents);
+      }
+      return epub;
+    } catch (error) {
+      epub.discardAndClose();
+      throw error;
     }
-    return epub;
   }
 }
 // Annotate the CommonJS export names for ESM import in node: