@storyteller-platform/epub 0.2.0

package/dist/index.js

@@ -0,0 +1,1810 @@
+import {
+  ERR_DUPLICATED_NAME,
+  Uint8ArrayReader,
+  Uint8ArrayWriter,
+  ZipReader,
+  ZipWriter
+} from "@zip.js/zip.js";
+import { Mutex } from "async-mutex";
+import { XMLBuilder, XMLParser } from "fast-xml-parser";
+import he from "he";
+import memoize from "mem";
+import { lookup } from "mime-types";
+import { nanoid } from "nanoid";
+import { dirname, resolve } from "@storyteller-platform/path";
+class EpubEntry {
+  filename;
+  entry = null;
+  data = null;
+  async getData() {
+    if (this.data) return this.data;
+    const writer = new Uint8ArrayWriter();
+    const data = await this.entry.getData(writer);
+    this.data = data;
+    return this.data;
+  }
+  setData(data) {
+    this.data = data;
+  }
+  constructor(entry) {
+    this.filename = entry.filename;
+    if ("data" in entry) {
+      this.data = entry.data;
+    } else {
+      this.entry = entry;
+    }
+  }
+}
+class Epub {
+  constructor(entries, onClose) {
+    this.entries = entries;
+    this.onClose = onClose;
+    this.dataWriter = new Uint8ArrayWriter();
+    this.zipWriter = new ZipWriter(this.dataWriter);
+    this.readXhtmlItemContents = memoize(
+      this.readXhtmlItemContents.bind(this),
+      // This isn't unnecessary, the generic here just isn't handling the
+      // overloaded method type correctly
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      { cacheKey: ([id, as]) => `${id}:${as ?? "xhtml"}` }
+    );
+  }
+  static xmlParser = new XMLParser({
+    allowBooleanAttributes: true,
+    preserveOrder: true,
+    ignoreAttributes: false,
+    parseTagValue: false
+  });
+  static xhtmlParser = new XMLParser({
+    allowBooleanAttributes: true,
+    alwaysCreateTextNode: true,
+    preserveOrder: true,
+    ignoreAttributes: false,
+    htmlEntities: true,
+    trimValues: false,
+    stopNodes: ["*.pre", "*.script"],
+    parseTagValue: false,
+    updateTag(_tagName, _jPath, attrs) {
+      if (attrs && "@_/" in attrs) {
+        delete attrs["@_/"];
+      }
+      return true;
+    }
+  });
+  static xmlBuilder = new XMLBuilder({
+    preserveOrder: true,
+    format: true,
+    ignoreAttributes: false,
+    suppressEmptyNode: true
+  });
+  static xhtmlBuilder = new XMLBuilder({
+    preserveOrder: true,
+    ignoreAttributes: false,
+    stopNodes: ["*.pre", "*.script"],
+    suppressEmptyNode: true
+  });
+  /**
+   * Format a duration, provided as a number of seconds, as
+   * a SMIL clock value, to be used for Media Overlays.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-duration
+   */
+  static formatSmilDuration(duration) {
+    const hours = Math.floor(duration / 3600);
+    const minutes = Math.floor(duration / 60 - hours * 60);
+    const secondsAndMillis = duration - minutes * 60 - hours * 3600;
+    const [seconds, millis] = secondsAndMillis.toFixed(2).split(".");
+    return `${hours.toString().padStart(2, "0")}:${minutes.toString().padStart(2, "0")}:${seconds.padStart(2, "0")}.${millis ?? "0"}`;
+  }
+  /**
+   * Given an XML structure representing a complete XHTML document,
+   * add a `link` element to the `head` of the document.
+   *
+   * This method modifies the provided XML structure.
+   */
+  static addLinkToXhtmlHead(xml, link) {
+    const html = Epub.findXmlChildByName("html", xml);
+    if (!html) throw new Error("Invalid XHTML document: no html element");
+    const head = Epub.findXmlChildByName("head", html.html);
+    if (!head) throw new Error("Invalid XHTML document: no head element");
+    head["head"].push({
+      link: [],
+      ":@": {
+        "@_rel": link.rel,
+        "@_href": link.href,
+        "@_type": link.type
+      }
+    });
+  }
+  /**
+   * Given an XML structure representing a complete XHTML document,
+   * return the sub-structure representing the children of the
+   * document's body element.
+   */
+  static getXhtmlBody(xml) {
+    const html = Epub.findXmlChildByName("html", xml);
+    if (!html) throw new Error("Invalid XHTML document: no html element");
+    const body = Epub.findXmlChildByName("body", html["html"]);
+    if (!body) throw new Error("Invalid XHTML document: No body element");
+    return body["body"];
+  }
+  static createXmlElement(name, properties, children = []) {
+    return {
+      ":@": Object.fromEntries(
+        Object.entries(properties).map(([prop, value]) => [`@_${prop}`, value])
+      ),
+      [name]: children
+    };
+  }
+  static createXmlTextNode(text) {
+    return { ["#text"]: text };
+  }
+  /**
+   * Given an XML structure representing a complete XHTML document,
+   * return a string representing the concatenation of all text nodes
+   * in the document.
+   */
+  static getXhtmlTextContent(xml) {
+    let text = "";
+    for (const child of xml) {
+      if (Epub.isXmlTextNode(child)) {
+        text += child["#text"];
+        continue;
+      }
+      const children = Epub.getXmlChildren(child);
+      text += Epub.getXhtmlTextContent(children);
+    }
+    return text;
+  }
+  /**
+   * Given an XMLElement, return its tag name.
+   */
+  static getXmlElementName(element) {
+    const keys = Object.keys(element);
+    const elementName = keys.find((key) => key !== ":@" && key !== "#text");
+    if (!elementName)
+      throw new Error(
+        `Invalid XML Element: missing tag name
+${JSON.stringify(element, null, 2)}`
+      );
+    return elementName;
+  }
+  /**
+   * Given an XMLElement, return a list of its children
+   */
+  static getXmlChildren(element) {
+    const elementName = Epub.getXmlElementName(element);
+    return element[elementName];
+  }
+  static replaceXmlChildren(element, children) {
+    const elementName = Epub.getXmlElementName(element);
+    element[elementName] = children;
+  }
+  /**
+   * Given an XML structure, find the first child matching
+   * the provided name and optional filter.
+   */
+  static findXmlChildByName(name, xml, filter) {
+    const element = xml.find((e) => name in e && (filter ? filter(e) : true));
+    return element;
+  }
+  /**
+   * Given an XMLNode, determine whether it represents
+   * a text node or an XML element.
+   */
+  static isXmlTextNode(node) {
+    return "#text" in node;
+  }
+  zipWriter;
+  dataWriter;
+  rootfile = null;
+  manifest = null;
+  spine = null;
+  packageMutex = new Mutex();
+  /**
+   * Close the Epub. Must be called before the Epub goes out
+   * of scope/is garbage collected.
+   */
+  async close() {
+    var _a;
+    await ((_a = this.onClose) == null ? void 0 : _a.call(this));
+    await this.zipWriter.close();
+  }
+  /**
+   * Construct an Epub instance, optionally beginning
+   * with the provided metadata.
+   *
+   * @param dublinCore Core metadata terms
+   * @param additionalMetadata An array of additional metadata entries
+   */
+  static async create({
+    title,
+    language,
+    identifier,
+    date,
+    subjects,
+    type,
+    creators,
+    contributors
+  }, additionalMetadata = []) {
+    const entries = [];
+    const encoder = new TextEncoder();
+    const container = encoder.encode(`<?xml version="1.0"?>
+<container>
+  <rootfiles>
+    <rootfile media-type="application/oebps-package+xml" full-path="OEBPS/content.opf"/>
+  </rootfiles>
+</container>
+`);
+    entries.push(
+      new EpubEntry({ filename: "META-INF/container.xml", data: 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">
+  <metadata>
+  </metadata>
+  <manifest>
+  </manifest>
+  <spine>
+  </spine>
+</package>
+`);
+    entries.push(
+      new EpubEntry({ filename: "OEBPS/content.opf", data: packageDocument })
+    );
+    const epub = new this(entries);
+    const metadata = [
+      {
+        id: "pub-id",
+        type: "dc:identifier",
+        properties: {},
+        value: identifier
+      },
+      ...additionalMetadata
+    ];
+    await Promise.all(metadata.map((entry) => epub.addMetadata(entry)));
+    await epub.setTitle(title);
+    await epub.setLanguage(language);
+    if (date) await epub.setPublicationDate(date);
+    if (type) await epub.setType(type);
+    if (subjects) {
+      await Promise.all(subjects.map((subject) => epub.addSubject(subject)));
+    }
+    if (creators) {
+      await Promise.all(creators.map((creator) => epub.addCreator(creator)));
+    }
+    if (contributors) {
+      await Promise.all(
+        contributors.map((contributor) => epub.addCreator(contributor))
+      );
+    }
+    return epub;
+  }
+  /**
+   * Construct an Epub instance by reading an existing EPUB
+   * publication.
+   *
+   * @param pathOrData Must be either a string representing the
+   *        path to an EPUB file on disk, or a Uint8Array representing
+   *        the data of the EPUB publication.
+   */
+  static async from(pathOrData) {
+    if (typeof pathOrData === "string") {
+      throw new Error("Import from /node to construct from a file");
+    }
+    const fileData = pathOrData;
+    const dataReader = new Uint8ArrayReader(fileData);
+    const zipReader = new ZipReader(dataReader);
+    const zipEntries = await zipReader.getEntries();
+    const epubEntries = zipEntries.map((entry) => new EpubEntry(entry));
+    const epub = new this(epubEntries, () => zipReader.close());
+    return epub;
+  }
+  getEntry(path) {
+    return this.entries.find((entry) => entry.filename === path);
+  }
+  async removeEntry(href) {
+    const rootfile = await this.getRootfile();
+    const filename = this.resolveHref(rootfile, href);
+    const index = this.entries.findIndex((entry) => entry.filename === filename);
+    if (index === -1) return;
+    this.entries.splice(index, 1);
+  }
+  async getFileData(path, encoding) {
+    const containerEntry = this.getEntry(path);
+    if (!containerEntry)
+      throw new Error(
+        `Could not get file data for entry ${path}: entry not found`
+      );
+    const containerContents = await containerEntry.getData();
+    return encoding === "utf-8" ? new TextDecoder("utf-8").decode(containerContents) : containerContents;
+  }
+  async getRootfile() {
+    var _a;
+    if (this.rootfile !== null) return this.rootfile;
+    const containerString = await this.getFileData(
+      "META-INF/container.xml",
+      "utf-8"
+    );
+    if (!containerString)
+      throw new Error("Failed to parse EPUB: Missing META-INF/container.xml");
+    const containerDocument = Epub.xmlParser.parse(containerString);
+    const container = Epub.findXmlChildByName("container", containerDocument);
+    if (!container)
+      throw new Error(
+        "Failed to parse EPUB container.xml: Found no container element"
+      );
+    const rootfiles = Epub.findXmlChildByName(
+      "rootfiles",
+      Epub.getXmlChildren(container)
+    );
+    if (!rootfiles)
+      throw new Error(
+        "Failed to parse EPUB container.xml: Found no rootfiles element"
+      );
+    const rootfile = Epub.findXmlChildByName(
+      "rootfile",
+      Epub.getXmlChildren(rootfiles),
+      (node) => {
+        var _a2;
+        return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_media-type"]) === "application/oebps-package+xml";
+      }
+    );
+    if (!((_a = rootfile == null ? void 0 : rootfile[":@"]) == null ? void 0 : _a["@_full-path"]))
+      throw new Error(
+        "Failed to parse EPUB container.xml: Found no rootfile element"
+      );
+    this.rootfile = rootfile[":@"]["@_full-path"];
+    return this.rootfile;
+  }
+  migratePackageDocument(packageDocument) {
+    for (const element of packageDocument) {
+      if (Epub.isXmlTextNode(element)) continue;
+      const elementName = Epub.getXmlElementName(element);
+      if (elementName.startsWith("opf:")) {
+        element[elementName.replace("opf:", "")] = Epub.getXmlChildren(element);
+        delete element[elementName];
+        this.migratePackageDocument(Epub.getXmlChildren(element));
+      }
+    }
+  }
+  async getPackageDocument() {
+    const rootfile = await this.getRootfile();
+    const packageDocumentString = await this.getFileData(rootfile, "utf-8");
+    if (!packageDocumentString)
+      throw new Error(
+        `Failed to parse EPUB: could not find package document at ${rootfile}`
+      );
+    const packageDocument = Epub.xmlParser.parse(
+      packageDocumentString
+    );
+    return packageDocument;
+  }
+  async getPackageElement() {
+    const packageDocument = await this.getPackageDocument();
+    const packageElement = Epub.findXmlChildByName("package", packageDocument) ?? Epub.findXmlChildByName("opf:package", packageDocument);
+    if (!packageElement) {
+      throw new Error(
+        "Failed to parse EPUB: Found no package element in package document"
+      );
+    }
+    this.migratePackageDocument(packageDocument);
+    return packageElement;
+  }
+  /**
+   * Safely modify the package document, without race conditions.
+   *
+   * Since the reading the package document is an async process,
+   * multiple simultaneously dispatched function calls that all
+   * attempt to modify it can clobber each other's changes. This
+   * method uses a mutex to ensure that each update runs exclusively.
+   *
+   * @param producer The function to update the package document. If
+   *    it returns a new package document, that will be persisted, otherwise
+   *    it will be assumed that the package document was modified in place.
+   */
+  async withPackage(producer) {
+    await this.packageMutex.runExclusive(async () => {
+      const packageDocument = await this.getPackageDocument();
+      const packageElement = Epub.findXmlChildByName("package", packageDocument) ?? Epub.findXmlChildByName("opf:package", packageDocument);
+      if (!packageElement) {
+        throw new Error(
+          "Failed to parse EPUB: Found no package element in package document"
+        );
+      }
+      const produced = await producer(packageElement);
+      const updatedPackageDocument = await Epub.xmlBuilder.build(
+        produced ?? packageDocument
+      );
+      const rootfile = await this.getRootfile();
+      this.writeEntryContents(rootfile, updatedPackageDocument, "utf-8");
+    });
+  }
+  /**
+   * Retrieve the manifest for the Epub.
+   *
+   * This is represented as a map from each manifest items'
+   * id to the rest of its properties.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+   */
+  async getManifest() {
+    if (this.manifest !== null) return this.manifest;
+    const packageElement = await this.getPackageElement();
+    const manifest = Epub.findXmlChildByName(
+      "manifest",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!manifest)
+      throw new Error(
+        "Failed to parse EPUB: Found no manifest element in package document"
+      );
+    this.manifest = Epub.getXmlChildren(manifest).reduce((acc, item) => {
+      var _a, _b;
+      if (Epub.isXmlTextNode(item)) return acc;
+      if (!((_a = item[":@"]) == null ? void 0 : _a["@_id"]) || !item[":@"]["@_href"]) {
+        return acc;
+      }
+      return {
+        ...acc,
+        [item[":@"]["@_id"]]: {
+          id: item[":@"]["@_id"],
+          href: item[":@"]["@_href"],
+          mediaType: item[":@"]["@_media-type"],
+          mediaOverlay: item[":@"]["@_media-overlay"],
+          fallback: item[":@"]["@_fallback"],
+          properties: (_b = item[":@"]["@_properties"]) == null ? void 0 : _b.split(" ")
+        }
+      };
+    }, {});
+    return this.manifest;
+  }
+  /**
+   * Returns the first index in the metadata element's children array
+   * that matches the provided predicate.
+   *
+   * Note: This may technically be different than the index in the
+   * getMetadata() array, as it includes non-metadata nodes, like
+   * text nodes. These are technically not allowed, but may exist,
+   * nonetheless. As consumers only ever see the getMetadata()
+   * array, this method is only meant to be used internally.
+   */
+  findMetadataIndex(packageElement, predicate) {
+    const metadataElement = Epub.findXmlChildByName(
+      "metadata",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!metadataElement)
+      throw new Error(
+        "Failed to parse EPUB: Found no metadata element in package document"
+      );
+    return metadataElement.metadata.findIndex((node) => {
+      const item = Epub.parseMetadataItem(node);
+      if (!item) return false;
+      return predicate(item);
+    });
+  }
+  /**
+   * Returns the item in the metadata element's children array
+   * that matches the provided predicate.
+   */
+  async findMetadataItem(predicate) {
+    const [first] = await this.findAllMetadataItems(predicate);
+    return first ?? null;
+  }
+  /**
+   * Returns the item in the metadata element's children array
+   * that matches the provided predicate.
+   */
+  async findAllMetadataItems(predicate) {
+    const packageElement = await this.getPackageElement();
+    const metadataElement = Epub.findXmlChildByName(
+      "metadata",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!metadataElement)
+      throw new Error(
+        "Failed to parse EPUB: Found no metadata element in package document"
+      );
+    const elements = metadataElement.metadata.filter((node) => {
+      const item = Epub.parseMetadataItem(node);
+      if (!item) return false;
+      return predicate(item);
+    });
+    return elements.map((element) => Epub.parseMetadataItem(element)).filter((item) => !!item);
+  }
+  static parseMetadataItem(node) {
+    if (Epub.isXmlTextNode(node)) return null;
+    const elementName = Epub.getXmlElementName(node);
+    const textNode = Epub.getXmlChildren(node)[0];
+    const value = !textNode || !Epub.isXmlTextNode(textNode) ? void 0 : textNode["#text"].replaceAll(/\s+/g, " ");
+    const attributes = node[":@"] ?? {};
+    const { id, ...properties } = Object.fromEntries(
+      Object.entries(attributes).map(([attrName, value2]) => [
+        attrName.slice(2),
+        value2
+      ])
+    );
+    return {
+      id,
+      type: elementName,
+      properties,
+      value
+    };
+  }
+  /**
+   * Retrieve the metadata entries for the Epub.
+   *
+   * This is represented as an array of metadata entries,
+   * in the order that they're presented in the Epub package document.
+   *
+   * For more useful semantic representations of metadata, use
+   * specific methods such as `getTitle()` and `getAuthors()`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+   */
+  async getMetadata() {
+    const packageElement = await this.getPackageElement();
+    const metadataElement = Epub.findXmlChildByName(
+      "metadata",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!metadataElement)
+      throw new Error(
+        "Failed to parse EPUB: Found no metadata element in package document"
+      );
+    const metadata = metadataElement.metadata.map((node) => Epub.parseMetadataItem(node)).filter((node) => !!node);
+    return metadata;
+  }
+  /**
+   * Even "EPUB 3" publications sometimes still only use the
+   * EPUB 2 specification for identifying the cover image.
+   * This is a private method that is used as a fallback if
+   * we fail to find the cover image according to the EPUB 3
+   * spec.
+   */
+  async getEpub2CoverImage() {
+    var _a;
+    const packageElement = await this.getPackageElement();
+    const metadataElement = Epub.findXmlChildByName(
+      "metadata",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!metadataElement)
+      throw new Error(
+        "Failed to parse EPUB: Found no metadata element in package document"
+      );
+    const coverImageElement = Epub.getXmlChildren(metadataElement).find(
+      (node) => {
+        var _a2;
+        return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_name"]) === "cover";
+      }
+    );
+    const manifestItemId = (_a = coverImageElement == null ? void 0 : coverImageElement[":@"]) == null ? void 0 : _a["@_content"];
+    if (!manifestItemId) return null;
+    const manifest = await this.getManifest();
+    return Object.values(manifest).find((item) => item.id === manifestItemId) ?? null;
+  }
+  /**
+   * Retrieve the cover image manifest item.
+   *
+   * This does not return the actual image data. To
+   * retrieve the image data, pass this item's id to
+   * epub.readItemContents, or use epub.getCoverImage()
+   * instead.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-cover-image
+   */
+  async getCoverImageItem() {
+    const manifest = await this.getManifest();
+    const coverImage = Object.values(manifest).find(
+      (item) => {
+        var _a;
+        return (_a = item.properties) == null ? void 0 : _a.includes("cover-image");
+      }
+    );
+    if (coverImage) return coverImage;
+    return this.getEpub2CoverImage();
+  }
+  /**
+   * Retrieve the cover image data as a byte array.
+   *
+   * This does not include, for example, the cover image's
+   * filename or mime type. To retrieve the image manifest
+   * item, use epub.getCoverImageItem().
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-cover-image
+   */
+  async getCoverImage() {
+    const coverImageItem = await this.getCoverImageItem();
+    if (!coverImageItem) return coverImageItem;
+    return this.readItemContents(coverImageItem.id);
+  }
+  /**
+   * Set the cover image for the EPUB.
+   *
+   * Adds a manifest item with the `cover-image` property, per
+   * the EPUB 3 spec, and then writes the provided image data to
+   * the provided href within the publication.
+   */
+  async setCoverImage(href, data) {
+    const coverImageItem = await this.getCoverImageItem();
+    if (coverImageItem) {
+      await this.removeManifestItem(coverImageItem.id);
+    }
+    const mediaType = lookup(href);
+    if (!mediaType)
+      throw new Error(`Invalid file extension for cover image: ${href}`);
+    await this.addManifestItem(
+      { id: "cover-image", href, mediaType, properties: ["cover-image"] },
+      data
+    );
+  }
+  /**
+   * Retrieve the publication date from the dc:date element
+   * in the EPUB metadata as a Date object.
+   *
+   * If there is no dc:date element, returns null.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcdate
+   */
+  async getPublicationDate() {
+    const metadata = await this.getMetadata();
+    const entry = metadata.find(({ type }) => type === "dc:date");
+    if (!(entry == null ? void 0 : entry.value)) return null;
+    return new Date(entry.value);
+  }
+  /**
+   * Set the dc:date metadata element with the provided date.
+   *
+   * Updates the existing dc:date element if one exists.
+   * Otherwise creates a new element
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcdate
+   */
+  async setPublicationDate(date) {
+    await this.replaceMetadata(({ type }) => type === "dc:date", {
+      type: "dc:date",
+      properties: {},
+      value: date.toISOString()
+    });
+  }
+  /**
+   * Set the dc:type metadata element.
+   *
+   * Updates the existing dc:type element if one exists.
+   * Otherwise creates a new element.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dctype
+   */
+  async setType(type) {
+    await this.replaceMetadata(({ type: type2 }) => type2 === "dc:type", {
+      type: "dc:type",
+      properties: {},
+      value: type
+    });
+  }
+  /**
+   * Retrieve the publication type from the dc:type element
+   * in the EPUB metadata.
+   *
+   * If there is no dc:type element, returns null.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dctype
+   */
+  async getType() {
+    const metadata = await this.getMetadata();
+    return metadata.find(({ type }) => type === "dc:type") ?? null;
+  }
+  /**
+   * Add a subject to the EPUB metadata.
+   *
+   * @param subject May be a string representing just a schema-less
+   *  subject name, or a DcSubject object
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
+   */
+  async addSubject(subject) {
+    const subjectEntry = typeof subject === "string" ? {
+      value: subject
+    } : subject;
+    const subjectId = nanoid();
+    await this.addMetadata({
+      id: subjectId,
+      type: "dc:subject",
+      properties: {},
+      value: subjectEntry.value
+    });
+    if ("authority" in subjectEntry) {
+      await this.addMetadata({
+        type: "meta",
+        properties: { refines: `#${subjectId}`, property: "authority" },
+        value: subjectEntry.authority
+      });
+      await this.addMetadata({
+        type: "meta",
+        properties: { refines: `#${subjectId}`, property: "term" },
+        value: subjectEntry.term
+      });
+    }
+  }
+  /**
+   * Remove a subject from the EPUB metadata.
+   *
+   * Removes the subject at the provided index. This index
+   * refers to the array returned by `epub.getSubjects()`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+   */
+  async removeSubject(index) {
+    await this.withPackage((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 subjectCount = null;
+      let metadataIndex = null;
+      for (const meta of Epub.getXmlChildren(metadata)) {
+        if (subjectCount === index) break;
+        metadataIndex = metadataIndex === null ? 0 : metadataIndex + 1;
+        if (Epub.isXmlTextNode(meta)) continue;
+        if (Epub.getXmlElementName(meta) !== "dc:subject") continue;
+        subjectCount = subjectCount === null ? 0 : subjectCount + 1;
+      }
+      if (subjectCount === null || metadataIndex === null) return;
+      Epub.getXmlChildren(metadata).splice(metadataIndex, 1);
+    });
+  }
+  /**
+   * Retrieve the list of subjects for this EPUB.
+   *
+   * Subjects without associated authority and term metadata
+   * will be returned as strings. Otherwise, they will
+   * be represented as DcSubject objects, with a value,
+   * authority, and term.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
+   */
+  async getSubjects() {
+    const metadata = await this.getMetadata();
+    const subjectEntries = metadata.filter(({ type }) => type === "dc:subject");
+    const subjects = subjectEntries.map(({ value }) => value).filter((value) => !!value);
+    metadata.forEach((entry) => {
+      if (entry.type !== "meta" || entry.properties["property"] !== "term" && entry.properties["property"] !== "authority") {
+        return;
+      }
+      const subjectIdref = entry.properties["refines"];
+      if (!subjectIdref) return;
+      const subjectId = subjectIdref.slice(1);
+      const index = subjectEntries.findIndex((entry2) => entry2.id === subjectId);
+      if (index === -1) return;
+      const subject = typeof subjects[index] === "string" ? { value: subjects[index], authority: void 0, term: void 0 } : (
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        subjects[index]
+      );
+      subject[entry.properties["property"]] = entry.value;
+      subjects.splice(index, 1, subject);
+    });
+    return subjects;
+  }
+  /**
+   * Retrieve the Epub's language as specified in its
+   * package document metadata.
+   *
+   * If no language metadata is specified, returns null.
+   * Returns the language as an Intl.Locale instance.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
+   */
+  async getLanguage() {
+    const metadata = await this.getMetadata();
+    const languageEntries = metadata.filter(
+      (entry) => entry.type === "dc:language"
+    );
+    const primaryLanguage = languageEntries[0];
+    if (!primaryLanguage) return null;
+    const locale = primaryLanguage.value;
+    if (!locale || locale.toLowerCase() === "und") return null;
+    return new Intl.Locale(locale);
+  }
+  /**
+   * Update the Epub's language metadata entry.
+   *
+   * Updates the existing dc:language element if one exists.
+   * Otherwise creates a new element
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
+   */
+  async setLanguage(locale) {
+    await this.replaceMetadata(({ type }) => type === "dc:language", {
+      type: "dc:language",
+      properties: {},
+      value: locale.toString()
+    });
+  }
+  /**
+   * Retrieve the title of the Epub.
+   *
+   * @param main Optional - whether to return only the first title segment
+   *  if multiple are found. Otherwise, will follow the spec to combine title
+   *  segments
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+   */
+  async getTitle(expanded = false) {
+    var _a;
+    const entries = await this.getTitles();
+    if (!expanded) {
+      const mainEntry = entries.find((entry) => entry.type === "main");
+      if (mainEntry) return mainEntry.title;
+      const shortEntry = entries.find((entry) => entry.type === "short");
+      if (shortEntry) return shortEntry.title;
+      return ((_a = entries[0]) == null ? void 0 : _a.title) ?? null;
+    }
+    const expandedEntry = entries.find((entry) => entry.type === "expanded");
+    if (expandedEntry) return expandedEntry.title;
+    return entries.map((entry) => entry.title).join(", ");
+  }
+  /**
+   * Retrieve the subtitle of the Epub, if it exists.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+   */
+  async getSubtitle() {
+    const entries = await this.getTitles();
+    const subtitleEntry = entries.find((entry) => entry.type === "subtitle");
+    return (subtitleEntry == null ? void 0 : subtitleEntry.title) ?? null;
+  }
+  /**
+   * Retrieve all title entries of the Epub.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+   */
+  async getTitles() {
+    const metadata = await this.getMetadata();
+    const titleEntries = metadata.filter((entry) => entry.type === "dc:title");
+    const titleRefinements = metadata.filter(
+      (entry) => entry.type === "meta" && entry.properties["refines"] && (entry.properties["property"] === "title-type" || entry.properties["property"] === "display-seq")
+    );
+    const sortedTitleParts = titleEntries.filter(
+      (titleEntry) => titleEntry.id && titleRefinements.some(
+        (entry) => {
+          var _a;
+          return entry.value && ((_a = entry.properties["refines"]) == null ? void 0 : _a.slice(1)) === titleEntry.id && entry.properties["property"] === "display-seq" && !Number.isNaN(parseInt(entry.value, 10));
+        }
+      )
+    ).sort((a, b) => {
+      const refinementA = titleRefinements.find(
+        (entry) => entry.properties["property"] === "display-seq" && entry.properties["refines"].slice(1) === a.id
+      );
+      const refinementB = titleRefinements.find(
+        (entry) => entry.properties["property"] === "display-seq" && entry.properties["refines"].slice(1) === b.id
+      );
+      const sortA = parseInt(refinementA.value, 10);
+      const sortB = parseInt(refinementB.value, 10);
+      return sortA - sortB;
+    });
+    return (sortedTitleParts.length === 0 ? titleEntries : sortedTitleParts).map((entry) => {
+      const titleType = titleRefinements.find(
+        (refinement) => {
+          var _a;
+          return ((_a = refinement.properties["refines"]) == null ? void 0 : _a.slice(1)) === entry.id && refinement.properties["property"] === "title-type";
+        }
+      );
+      return {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        title: entry.value,
+        type: (titleType == null ? void 0 : titleType.value) ?? null
+      };
+    });
+  }
+  /**
+   * Update the Epub's description metadata entry.
+   *
+   * Updates the existing dc:description element if one exists.
+   * Otherwise creates a new element. Any non-ASCII symbols,
+   * `&`, `<`, `>`, `"`, `'`, and `\``` will be encoded as HTML entities.
+   */
+  async setDescription(description) {
+    await this.replaceMetadata(({ type }) => type === "dc:description", {
+      type: "dc:description",
+      value: he.encode(description),
+      properties: {}
+    });
+  }
+  /**
+   * Retrieve the Epub's description as specified in its
+   * package document metadata.
+   *
+   * If no description metadata is specified, returns null.
+   * Returns the description as a string. Descriptions may
+   * include HTML markup.
+   */
+  async getDescription() {
+    const metadata = await this.getMetadata();
+    const descriptionEntry = metadata.find(
+      (entry) => entry.type === "dc:description"
+    );
+    if (!(descriptionEntry == null ? void 0 : descriptionEntry.value)) return null;
+    const escaped = descriptionEntry.value;
+    return he.decode(escaped);
+  }
+  /**
+   * Return the set of custom vocabulary prefixes set on this publication's
+   * root package element.
+   *
+   * Returns a map from prefix to URI
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
+   */
+  async getPackageVocabularyPrefixes() {
+    var _a;
+    const packageElement = await this.getPackageElement();
+    const prefixValue = (_a = packageElement[":@"]) == null ? void 0 : _a["@_prefix"];
+    if (!prefixValue) return {};
+    const matches = prefixValue.matchAll(/(?:([a-z]+): +(\S+)\s*)/gs);
+    return Array.from(matches).reduce(
+      (acc, match) => match[1] && match[2] ? { ...acc, [match[1]]: match[2] } : acc,
+      {}
+    );
+  }
+  /**
+   * Set a custom vocabulary prefix on the root package element.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
+   */
+  async setPackageVocabularyPrefix(prefix, uri) {
+    await this.withPackage(async (packageElement) => {
+      const prefixes = await this.getPackageVocabularyPrefixes();
+      prefixes[prefix] = uri;
+      packageElement[":@"] ??= {};
+      packageElement[":@"]["@_prefix"] = Object.entries(prefixes).map(([p, u]) => `${p}: ${u}`).join("\n    ");
+    });
+  }
+  /**
+   * Set the title of the Epub.
+   *
+   * This will replace all existing dc:title elements with
+   * this title. It will be given title-type "main".
+   *
+   * To set specific titles and their types, use epub.setTitles().
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+   */
+  // TODO: This should allow users to optionally specify an array,
+  // rather than a single string, to support expanded titles.
+  async setTitle(title) {
+    await this.withPackage((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"
+        );
+      const titleElement = Epub.findXmlChildByName(
+        "dc:title",
+        metadata.metadata
+      );
+      if (!titleElement) {
+        Epub.getXmlChildren(metadata).push(
+          Epub.createXmlElement("dc:title", {}, [
+            Epub.createXmlTextNode(title)
+          ])
+        );
+      } else {
+        titleElement["dc:title"] = [Epub.createXmlTextNode(title)];
+      }
+    });
+  }
+  async setTitles(entries) {
+    await this.withPackage((packageElement) => {
+      var _a, _b;
+      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 metadataEntries = Epub.getXmlChildren(metadata);
+      for (let i = metadataEntries.length - 1; i >= 0; i--) {
+        const meta = metadataEntries[i];
+        if (Epub.isXmlTextNode(meta)) continue;
+        if (Epub.getXmlElementName(meta) === "dc:title" || ((_a = meta[":@"]) == null ? void 0 : _a["@_property"]) === "title-type" || ((_b = meta[":@"]) == null ? void 0 : _b["@_property"]) === "display-seq") {
+          metadataEntries.splice(i, 1);
+        }
+      }
+      for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const id = nanoid();
+        metadataEntries.push(
+          Epub.createXmlElement("dc:title", { id }, [
+            Epub.createXmlTextNode(entry.title)
+          ])
+        );
+        if (entry.type) {
+          metadataEntries.push(
+            Epub.createXmlElement(
+              "meta",
+              { refines: `#${id}`, property: "title-type" },
+              [Epub.createXmlTextNode(entry.type)]
+            )
+          );
+        }
+        metadataEntries.push(
+          Epub.createXmlElement(
+            "meta",
+            { refines: `#${id}`, property: "display-seq" },
+            [Epub.createXmlTextNode((i + 1).toString())]
+          )
+        );
+      }
+    });
+  }
+  /**
+   * Retrieve the list of collections.
+   */
+  async getCollections() {
+    var _a, _b;
+    const metadata = await this.getMetadata();
+    const collections = [];
+    for (const entry of metadata) {
+      if (entry.properties["property"] === "belongs-to-collection" && entry.value) {
+        const type = (_a = metadata.find(
+          (e) => e.properties["refines"] === `#${entry.id ?? ""}` && e.properties["property"] === "collection-type"
+        )) == null ? void 0 : _a.value;
+        const position = (_b = metadata.find(
+          (e) => e.properties["refines"] === `#${entry.id ?? ""}` && e.properties["property"] === "group-position"
+        )) == null ? void 0 : _b.value;
+        collections.push({
+          name: entry.value,
+          ...type && { type },
+          ...position && { position }
+        });
+      }
+    }
+    return collections;
+  }
+  /**
+   * Add a collection to the EPUB metadata.
+   *
+   * If index is provided, the collection will be placed at
+   * that index in the list of collections. Otherwise, it
+   * will be added to the end of the list.
+   */
+  async addCollection(collection, index) {
+    const collectionId = nanoid();
+    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"
+        );
+      let collectionCount = 0;
+      let metadataIndex = 0;
+      for (const meta of Epub.getXmlChildren(metadata)) {
+        if (collectionCount === index) break;
+        metadataIndex++;
+        if (Epub.isXmlTextNode(meta)) continue;
+        if (Epub.getXmlElementName(meta) !== "meta") continue;
+        if (((_a = meta[":@"]) == null ? void 0 : _a["@_property"]) !== "belongs-to-collection") continue;
+        collectionCount++;
+      }
+      Epub.getXmlChildren(metadata).splice(
+        metadataIndex,
+        0,
+        Epub.createXmlElement(
+          "meta",
+          { id: collectionId, property: "belongs-to-collection" },
+          [Epub.createXmlTextNode(collection.name)]
+        )
+      );
+    });
+    if (collection.position) {
+      await this.addMetadata({
+        type: "meta",
+        properties: { refines: `#${collectionId}`, property: "group-position" },
+        value: collection.position
+      });
+    }
+    if (collection.type) {
+      await this.addMetadata({
+        type: "meta",
+        properties: {
+          refines: `#${collectionId}`,
+          property: "collection-type"
+        },
+        value: collection.type
+      });
+    }
+  }
+  /**
+   * Remove a collection from the EPUB metadata.
+   *
+   * Removes the collection at the provided index. This index
+   * refers to the array returned by `epub.getCollections()`.
+   */
+  async removeCollection(index) {
+    await this.withPackage((packageElement) => {
+      var _a, _b;
+      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 collectionCount = null;
+      let metadataIndex = null;
+      for (const meta of Epub.getXmlChildren(metadata)) {
+        if (collectionCount === index) break;
+        metadataIndex = metadataIndex === null ? 0 : metadataIndex + 1;
+        if (Epub.isXmlTextNode(meta)) continue;
+        if (Epub.getXmlElementName(meta) !== "meta") continue;
+        if (((_a = meta[":@"]) == null ? void 0 : _a["@_property"]) !== "belongs-to-collection") continue;
+        collectionCount = collectionCount === null ? 0 : collectionCount + 1;
+      }
+      if (collectionCount === null || metadataIndex === null) return;
+      const [removed] = Epub.getXmlChildren(metadata).splice(metadataIndex, 1);
+      if (removed && !Epub.isXmlTextNode(removed) && ((_b = removed[":@"]) == null ? void 0 : _b["@_id"])) {
+        const id = removed[":@"]["@_id"];
+        const newChildren = Epub.getXmlChildren(metadata).filter((node) => {
+          var _a2;
+          if (Epub.isXmlTextNode(node)) return true;
+          if (Epub.getXmlElementName(node) !== "meta") return true;
+          if (((_a2 = node[":@"]) == null ? void 0 : _a2["@_refines"]) !== `#${id}`) return true;
+          return false;
+        });
+        Epub.replaceXmlChildren(metadata, newChildren);
+      }
+    });
+  }
+  /**
+   * Retrieve the list of creators.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+   */
+  async getCreators(type = "creator") {
+    const metadata = await this.getMetadata();
+    const creatorEntries = metadata.filter(
+      (entry) => entry.type === `dc:${type}`
+    );
+    const creators = creatorEntries.map(({ value }) => value).filter((value) => !!value).map((value) => ({ name: value }));
+    metadata.forEach((entry) => {
+      if (entry.type !== "meta" || entry.properties["property"] !== "file-as" && entry.properties["property"] !== "role" && entry.properties["property"] !== "alternate-script" || !entry.value) {
+        return;
+      }
+      const creatorIdref = entry.properties["refines"];
+      if (!creatorIdref) return;
+      const creatorId = creatorIdref.slice(1);
+      const index = creatorEntries.findIndex((entry2) => entry2.id === creatorId);
+      if (index === -1) return;
+      const creator = creators[index];
+      if (entry.properties["alternate-script"]) {
+        if (!entry.properties["xml:lang"]) return;
+        creator.alternateScripts ??= [];
+        creator.alternateScripts.push({
+          name: entry.value,
+          locale: new Intl.Locale(entry.properties["xml:lang"])
+        });
+        return;
+      }
+      const prop = entry.properties["property"] === "file-as" ? "fileAs" : "role";
+      creator[prop] = entry.value;
+      if (prop === "role" && entry.properties["scheme"]) {
+        creator.roleScheme = entry.properties["scheme"];
+      }
+    });
+    return creators;
+  }
+  /**
+   * Retrieve the list of contributors.
+   *
+   * This is a convenience method for
+   * `epub.getCreators('contributor')`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccontributor
+   */
+  getContributors() {
+    return this.getCreators("contributor");
+  }
+  /**
+   * Add a creator to the EPUB metadata.
+   *
+   * If index is provided, the creator will be placed at
+   * that index in the list of creators. Otherwise, it
+   * will be added to the end of the list.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+   */
+  async addCreator(creator, index, type = "creator") {
+    const creatorId = nanoid();
+    await this.withPackage((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 creatorCount = 0;
+      let metadataIndex = 0;
+      for (const meta of Epub.getXmlChildren(metadata)) {
+        if (creatorCount === index) break;
+        metadataIndex++;
+        if (Epub.isXmlTextNode(meta)) continue;
+        if (Epub.getXmlElementName(meta) !== `dc:${type}`) continue;
+        creatorCount++;
+      }
+      Epub.getXmlChildren(metadata).splice(
+        metadataIndex,
+        0,
+        Epub.createXmlElement(`dc:${type}`, { id: creatorId }, [
+          Epub.createXmlTextNode(creator.name)
+        ])
+      );
+    });
+    if (creator.role) {
+      await this.addMetadata({
+        type: "meta",
+        properties: {
+          refines: `#${creatorId}`,
+          property: "role",
+          ...creator.roleScheme && { scheme: creator.roleScheme }
+        },
+        value: creator.role
+      });
+    }
+    if (creator.fileAs) {
+      await this.addMetadata({
+        type: "meta",
+        properties: { refines: `#${creatorId}`, property: "file-as" },
+        value: creator.fileAs
+      });
+    }
+    if (creator.alternateScripts) {
+      for (const alternate of creator.alternateScripts) {
+        await this.addMetadata({
+          type: "meta",
+          properties: {
+            refines: `#${creatorId}`,
+            property: "alternate-script",
+            "xml:lang": alternate.locale.toString()
+          },
+          value: alternate.name
+        });
+      }
+    }
+  }
+  /**
+   * Remove a creator from the EPUB metadata.
+   *
+   * Removes the creator at the provided index. This index
+   * refers to the array returned by `epub.getCreators()`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+   */
+  async removeCreator(index, type = "creator") {
+    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"
+        );
+      let creatorCount = null;
+      let metadataIndex = null;
+      for (const meta of Epub.getXmlChildren(metadata)) {
+        if (creatorCount === index) break;
+        metadataIndex = metadataIndex === null ? 0 : metadataIndex + 1;
+        if (Epub.isXmlTextNode(meta)) continue;
+        if (Epub.getXmlElementName(meta) !== `dc:${type}`) continue;
+        creatorCount = creatorCount === null ? 0 : creatorCount + 1;
+      }
+      if (creatorCount === null || metadataIndex === null) return;
+      const [removed] = Epub.getXmlChildren(metadata).splice(metadataIndex, 1);
+      if (removed && !Epub.isXmlTextNode(removed) && ((_a = removed[":@"]) == null ? void 0 : _a["@_id"])) {
+        const id = removed[":@"]["@_id"];
+        const newChildren = Epub.getXmlChildren(metadata).filter((node) => {
+          var _a2;
+          if (Epub.isXmlTextNode(node)) return true;
+          if (Epub.getXmlElementName(node) !== "meta") return true;
+          if (((_a2 = node[":@"]) == null ? void 0 : _a2["@_refines"]) !== `#${id}`) return true;
+          return false;
+        });
+        Epub.replaceXmlChildren(metadata, newChildren);
+      }
+    });
+  }
+  /**
+   * Remove a contributor from the EPUB metadata.
+   *
+   * Removes the contributor at the provided index. This index
+   * refers to the array returned by `epub.getContributors()`.
+   *
+   * This is a convenience method for
+   * `epub.removeCreator(index, 'contributor')`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+   */
+  async removeContributor(index) {
+    return this.removeCreator(index, "contributor");
+  }
+  /**
+   * Add a contributor to the EPUB metadata.
+   *
+   * If index is provided, the creator will be placed at
+   * that index in the list of creators. Otherwise, it
+   * will be added to the end of the list.
+   *
+   * This is a convenience method for
+   * `epub.addCreator(contributor, index, 'contributor')`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+   */
+  addContributor(contributor, index) {
+    return this.addCreator(contributor, index, "contributor");
+  }
+  async getSpine() {
+    if (this.spine !== null) return this.spine;
+    const packageElement = await this.getPackageElement();
+    const spine = Epub.findXmlChildByName(
+      "spine",
+      Epub.getXmlChildren(packageElement)
+    );
+    if (!spine)
+      throw new Error(
+        "Failed to parse EPUB: Found no spine element in package document"
+      );
+    this.spine = spine["spine"].filter((node) => !Epub.isXmlTextNode(node)).map((itemref) => {
+      var _a;
+      return (_a = itemref[":@"]) == null ? void 0 : _a["@_idref"];
+    }).filter((idref) => !!idref);
+    return this.spine;
+  }
+  /**
+   * Retrieve the manifest items that make up the Epub's spine.
+   *
+   * The spine specifies the order that the contents of the Epub
+   * should be displayed to users by default.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+   */
+  async getSpineItems() {
+    const spine = await this.getSpine();
+    const manifest = await this.getManifest();
+    return spine.map((itemref) => manifest[itemref]).filter((entry) => !!entry);
+  }
+  /**
+   * Add an item to the spine of the EPUB.
+   *
+   * If `index` is undefined, the item will be added
+   * to the end of the spine. Otherwise it will be
+   * inserted at the specified index.
+   *
+   * If the manifestId does not correspond to an item
+   * in the manifest, this will throw an error.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+   */
+  async addSpineItem(manifestId, index) {
+    const item = Epub.createXmlElement("itemref", { idref: manifestId });
+    const manifest = await this.getManifest();
+    const manifestItem = manifest[manifestId];
+    if (!manifestItem)
+      throw new Error(`Manifest item not found with id "${manifestId}"`);
+    await this.withPackage((packageElement) => {
+      const spine = Epub.findXmlChildByName(
+        "spine",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!spine)
+        throw new Error(
+          "Failed to parse EPUB: Found no spine element in package document"
+        );
+      if (index === void 0) {
+        Epub.getXmlChildren(spine).push(item);
+      } else {
+        Epub.getXmlChildren(spine).splice(index, 0, item);
+      }
+    });
+    this.spine = null;
+  }
+  /**
+   * Remove the spine item at the specified index.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+   */
+  async removeSpineItem(index) {
+    await this.withPackage((packageElement) => {
+      const spine = Epub.findXmlChildByName(
+        "spine",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!spine)
+        throw new Error(
+          "Failed to parse EPUB: Found no spine element in package document"
+        );
+      Epub.getXmlChildren(spine).splice(index, 1);
+    });
+    this.spine = null;
+  }
+  /**
+   * Returns a Zip Entry path for an HREF
+   */
+  resolveHref(from, href) {
+    const startPath = dirname(from);
+    const absoluteStartPath = startPath.startsWith("/") ? startPath : `/${startPath}`;
+    return resolve(absoluteStartPath, href).slice(1);
+  }
+  async readItemContents(id, encoding) {
+    const rootfile = await this.getRootfile();
+    const manifest = await this.getManifest();
+    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 itemEntry = encoding ? await this.getFileData(path, encoding) : await this.getFileData(path);
+    return itemEntry;
+  }
+  /**
+   * Create a new XHTML document with the given body
+   * and head.
+   *
+   * @param body The XML nodes to place in the body of the document
+   * @param head Optional - the XMl nodes to place in the head
+   * @param language Optional - defaults to the EPUB's language
+   */
+  async createXhtmlDocument(body, head, language) {
+    const lang = language ?? await this.getLanguage();
+    return [
+      Epub.createXmlElement("?xml", { version: "1.0", encoding: "UTF-8" }),
+      Epub.createXmlElement(
+        "html",
+        {
+          xmlns: "http://www.w3.org/1999/xhtml",
+          "xmlns:epub": "http://www.idpf.org/2007/ops",
+          ...lang && { "xml:lang": lang.toString(), lang: lang.toString() }
+        },
+        [
+          Epub.createXmlElement("head", {}, head),
+          Epub.createXmlElement("body", {}, body)
+        ]
+      )
+    ];
+  }
+  async readXhtmlItemContents(id, as = "xhtml") {
+    const contents = await this.readItemContents(id, "utf-8");
+    const xml = Epub.xhtmlParser.parse(contents);
+    if (as === "xhtml") return xml;
+    const body = Epub.getXhtmlBody(xml);
+    return Epub.getXhtmlTextContent(body);
+  }
+  writeEntryContents(path, contents, encoding) {
+    const data = encoding === "utf-8" ? new TextEncoder().encode(contents) : contents;
+    const entry = this.getEntry(path);
+    if (!entry) throw new Error(`Could not find file at ${path} in EPUB`);
+    entry.setData(data);
+  }
+  async writeItemContents(id, contents, encoding) {
+    const rootfile = await this.getRootfile();
+    const manifest = await this.getManifest();
+    const manifestItem = manifest[id];
+    if (!manifestItem)
+      throw new Error(`Could not find item with id "${id}" in manifest`);
+    memoize.clear(this.readXhtmlItemContents);
+    const href = this.resolveHref(rootfile, manifestItem.href);
+    if (encoding === "utf-8") {
+      this.writeEntryContents(href, contents, encoding);
+    } else {
+      this.writeEntryContents(href, contents);
+    }
+  }
+  /**
+   * Write new contents for an existing XHTML item,
+   * specified by its id.
+   *
+   * The id must reference an existing manifest item. If
+   * creating a new item, use `epub.addManifestItem()` instead.
+   *
+   * @param id The id of the manifest item to write new contents for
+   * @param contents The new contents. Must be a parsed XML tree.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-xhtml
+   */
+  async writeXhtmlItemContents(id, contents) {
+    await this.writeItemContents(
+      id,
+      Epub.xhtmlBuilder.build(contents),
+      "utf-8"
+    );
+  }
+  async removeManifestItem(id) {
+    await this.withPackage(async (packageElement) => {
+      var _a;
+      const manifest = Epub.findXmlChildByName(
+        "manifest",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!manifest)
+        throw new Error(
+          "Failed to parse EPUB: Found no manifest element in package document"
+        );
+      const itemIndex = Epub.getXmlChildren(manifest).findIndex(
+        (node) => {
+          var _a2;
+          return !Epub.isXmlTextNode(node) && ((_a2 = node[":@"]) == null ? void 0 : _a2["@_id"]) === id;
+        }
+      );
+      if (itemIndex === -1) return;
+      const [item] = Epub.getXmlChildren(manifest).splice(itemIndex, 1);
+      if (!item || Epub.isXmlTextNode(item) || !((_a = item[":@"]) == null ? void 0 : _a["@_href"])) return;
+      await this.removeEntry(item[":@"]["@_href"]);
+    });
+    this.manifest = null;
+  }
+  async addManifestItem(item, contents, encoding) {
+    await this.withPackage((packageElement) => {
+      const manifest = Epub.findXmlChildByName(
+        "manifest",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!manifest)
+        throw new Error(
+          "Failed to parse EPUB: Found no manifest element in package document"
+        );
+      Epub.getXmlChildren(manifest).push(
+        Epub.createXmlElement("item", {
+          id: item.id,
+          href: item.href,
+          ...item.mediaType && { "media-type": item.mediaType },
+          ...item.fallback && { fallback: item.fallback },
+          ...item.mediaOverlay && { "media-overlay": item.mediaOverlay },
+          ...item.properties && { properties: item.properties.join(" ") }
+        })
+      );
+    });
+    this.manifest = null;
+    const rootfile = await this.getRootfile();
+    const filename = this.resolveHref(rootfile, item.href);
+    const data = encoding === "utf-8" || encoding === "xml" ? new TextEncoder().encode(
+      encoding === "utf-8" ? contents : await Epub.xmlBuilder.build(
+        contents
+      )
+    ) : contents;
+    this.entries.push(new EpubEntry({ filename, data }));
+  }
+  /**
+   * Update the manifest entry for an existing item.
+   *
+   * To update the contents of an entry, use `epub.writeItemContents()`
+   * or `epub.writeXhtmlItemContents()`
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+   */
+  async updateManifestItem(id, newItem) {
+    await this.withPackage((packageElement) => {
+      const manifest = Epub.findXmlChildByName(
+        "manifest",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!manifest)
+        throw new Error(
+          "Failed to parse EPUB: Found no manifest element in package document"
+        );
+      const itemIndex = manifest["manifest"].findIndex(
+        (item) => {
+          var _a;
+          return !Epub.isXmlTextNode(item) && ((_a = item[":@"]) == null ? void 0 : _a["@_id"]) === id;
+        }
+      );
+      Epub.getXmlChildren(manifest).splice(
+        itemIndex,
+        1,
+        Epub.createXmlElement("item", {
+          id,
+          href: newItem.href,
+          ...newItem.mediaType && { "media-type": newItem.mediaType },
+          ...newItem.fallback && { fallback: newItem.fallback },
+          ...newItem.mediaOverlay && {
+            "media-overlay": newItem.mediaOverlay
+          },
+          ...newItem.properties && {
+            properties: newItem.properties.join(" ")
+          }
+        })
+      );
+    });
+    this.manifest = null;
+  }
+  /**
+   * Add a new metadata entry to the Epub.
+   *
+   * This method, like `epub.getMetadata()`, operates on
+   * metadata entries. For more useful semantic representations
+   * of metadata, use specific methods such as `setTitle()` and
+   * `setLanguage()`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+   */
+  async addMetadata(entry) {
+    await this.withPackage((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"
+        );
+      Epub.getXmlChildren(metadata).push(
+        Epub.createXmlElement(
+          entry.type,
+          {
+            ...entry.id && { id: entry.id },
+            ...entry.properties
+          },
+          entry.value !== void 0 ? [Epub.createXmlTextNode(entry.value)] : []
+        )
+      );
+    });
+  }
+  /**
+   * Replace a metadata entry with a new one.
+   *
+   * The `predicate` argument will be used to determine which entry
+   * to replace. The first metadata entry that matches the
+   * predicate will be replaced.
+   *
+   * @param predicate Calls predicate once for each metadata entry,
+   *  until it finds one where predicate returns true
+   * @param entry The new entry to replace the found entry with
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+   */
+  async replaceMetadata(predicate, entry) {
+    await this.withPackage((packageElement) => {
+      const metadataElement = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadataElement)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const oldEntryIndex = this.findMetadataIndex(packageElement, predicate);
+      const newElement = Epub.createXmlElement(
+        entry.type,
+        {
+          ...entry.id && { id: entry.id },
+          ...entry.properties
+        },
+        entry.value !== void 0 ? [Epub.createXmlTextNode(entry.value)] : []
+      );
+      if (oldEntryIndex === -1) {
+        metadataElement.metadata.push(newElement);
+      } else {
+        metadataElement.metadata.splice(oldEntryIndex, 1, newElement);
+      }
+    });
+  }
+  /**
+   * Remove one or more metadata entries.
+   *
+   * The `predicate` argument will be used to determine which entries
+   * to remove. The all metadata entries that match the
+   * predicate will be removed.
+   *
+   * @param predicate Calls predicate once for each metadata entry,
+   *  removing any for which it returns true
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+   */
+  async removeMetadata(predicate) {
+    await this.withPackage((packageElement) => {
+      const metadataElement = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadataElement) {
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      }
+      const metadataEntries = Epub.getXmlChildren(metadataElement);
+      for (let i = metadataEntries.length - 1; i >= 0; i--) {
+        const meta = metadataEntries[i];
+        const item = Epub.parseMetadataItem(meta);
+        if (!item) continue;
+        if (predicate(item)) {
+          metadataEntries.splice(i, 1);
+        }
+      }
+    });
+  }
+  /**
+   * Write the current contents of the Epub to a new
+   * Uint8Array.
+   *
+   * This _does not_ close the Epub. It can continue to
+   * be modified after it has been written to disk. Use
+   * `epub.close()` to close the Epub.
+   *
+   * When this method is called, the "dcterms:modified"
+   * meta tag is automatically updated to the current UTC
+   * timestamp.
+   */
+  async writeToArray() {
+    await this.replaceMetadata(
+      (entry) => entry.properties["property"] === "dcterms:modified",
+      {
+        type: "meta",
+        properties: { property: "dcterms:modified" },
+        // We need UTC with integer seconds, but toISOString gives UTC with ms
+        value: (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+/, "")
+      }
+    );
+    let mimetypeEntry = this.getEntry("mimetype");
+    if (!mimetypeEntry) {
+      mimetypeEntry = new EpubEntry({
+        filename: "mimetype",
+        data: new TextEncoder().encode("application/epub+zip")
+      });
+      this.entries.push(mimetypeEntry);
+    }
+    const mimetypeReader = new Uint8ArrayReader(await mimetypeEntry.getData());
+    try {
+      await this.zipWriter.add(mimetypeEntry.filename, mimetypeReader, {
+        level: 0,
+        extendedTimestamp: false
+      });
+    } catch (e) {
+      if (e instanceof Error && e.message === ERR_DUPLICATED_NAME) {
+        throw new Error(
+          `Failed to add file "${mimetypeEntry.filename}" to zip archive: ${e.message}`
+        );
+      }
+      throw e;
+    }
+    await Promise.all(
+      this.entries.map(async (entry) => {
+        if (entry.filename === "mimetype") return;
+        const reader = new Uint8ArrayReader(await entry.getData());
+        try {
+          return await this.zipWriter.add(entry.filename, reader);
+        } catch (e) {
+          if (e instanceof Error && e.message === ERR_DUPLICATED_NAME) {
+            throw new Error(
+              `Failed to add file "${entry.filename}" to zip archive: ${e.message}`
+            );
+          }
+          throw e;
+        }
+      })
+    );
+    const data = await this.zipWriter.close();
+    this.dataWriter = new Uint8ArrayWriter();
+    this.zipWriter = new ZipWriter(this.dataWriter);
+    return data;
+  }
+}
+export {
+  Epub
+};