@storyteller-platform/epub 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1,2 +1,5 @@
 import 'fast-xml-parser';
-export { A as AlternateScript, C as Collection, e as DcCreator, D as DcSubject, f as DublinCore, E as ElementName, k as Epub, Epub2UpgradeOptions, d as EpubMetadata, j as EpubVersionError, Landmark, M as ManifestItem, c as MetadataEntry, h as Navigation, N as NavigationItem, g as NavigationList, i as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.cjs';
+export { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind } from './adapters/interface.cjs';
+export { A as AlternateScript, C as Collection, e as DcCreator, D as DcSubject, f as DublinCore, E as ElementName, m as Epub, Epub2UpgradeOptions, o as EpubFactory, n as EpubInstanceFor, d as EpubMetadata, l as EpubReadOnlyError, j as EpubReader, k as EpubVersionError, F as FromOptions, I as InMemoryEpubReader, Landmark, M as ManifestItem, c as MetadataEntry, h as Navigation, N as NavigationItem, g as NavigationList, i as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.cjs';
+export { MemoryAdapter, MemoryAdapterOptions } from './adapters/memory.cjs';
+export { TmpFsAdapter } from './adapters/tmpfs.cjs';

package/dist/index.d.ts

@@ -1,2 +1,5 @@
 import 'fast-xml-parser';
-export { A as AlternateScript, C as Collection, e as DcCreator, D as DcSubject, f as DublinCore, E as ElementName, k as Epub, Epub2UpgradeOptions, d as EpubMetadata, j as EpubVersionError, Landmark, M as ManifestItem, c as MetadataEntry, h as Navigation, N as NavigationItem, g as NavigationList, i as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.js';
+export { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind } from './adapters/interface.js';
+export { A as AlternateScript, C as Collection, e as DcCreator, D as DcSubject, f as DublinCore, E as ElementName, m as Epub, Epub2UpgradeOptions, o as EpubFactory, n as EpubInstanceFor, d as EpubMetadata, l as EpubReadOnlyError, j as EpubReader, k as EpubVersionError, F as FromOptions, I as InMemoryEpubReader, Landmark, M as ManifestItem, c as MetadataEntry, h as Navigation, N as NavigationItem, g as NavigationList, i as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.js';
+export { MemoryAdapter, MemoryAdapterOptions } from './adapters/memory.js';
+export { TmpFsAdapter } from './adapters/tmpfs.js';

package/dist/index.js

@@ -1,52 +1,37 @@
-import {
-  __callDispose,
-  __using
-} from "./chunk-BIEQXUOY.js";
-import { randomUUID } from "node:crypto";
-import { createWriteStream, rmSync } from "node:fs";
-import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { pipeline } from "node:stream/promises";
+import "./chunk-BIEQXUOY.js";
+import { cp, mkdir } from "node:fs/promises";
 import { Mutex } from "async-mutex";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 import memoize from "mem";
 import { lookup } from "mime-types";
 import { nanoid } from "nanoid";
-import { fromBuffer, open } from "yauzl-promise";
-import { ZipFile } from "yazl";
-import { dirname, join, resolve } from "@storyteller-platform/path";
+import {
+  dirname,
+  hrefToPlatformPath,
+  join,
+  resolve
+} from "@storyteller-platform/path";
+import { TmpFsAdapter } from "./adapters/tmpfs.js";
 import * as Upgrade from "./upgrade.js";
-const MP3_FILE_EXTENSIONS = [".mp3"];
-const MPEG4_FILE_EXTENSIONS = [".mp4", ".m4a", ".m4b"];
-const AAC_FILE_EXTENSIONS = [".aac"];
-const OGG_FILE_EXTENSIONS = [".ogg", ".oga", ".mogg"];
-const OPUS_FILE_EXTENSIONS = [".opus"];
-const WAVE_FILE_EXTENSIONS = [".wav"];
-const AIFF_FILE_EXTENSIONS = [".aiff"];
-const FLAC_FILE_EXTENSIONS = [".flac"];
-const ALAC_FILE_EXTENSIONS = [".alac"];
-const WEBM_FILE_EXTENSIONS = [".weba"];
-const AUDIO_FILE_EXTENSIONS = [
-  ...MP3_FILE_EXTENSIONS,
-  ...AAC_FILE_EXTENSIONS,
-  ...MPEG4_FILE_EXTENSIONS,
-  ...OPUS_FILE_EXTENSIONS,
-  ...OGG_FILE_EXTENSIONS,
-  ...WAVE_FILE_EXTENSIONS,
-  ...AIFF_FILE_EXTENSIONS,
-  ...FLAC_FILE_EXTENSIONS,
-  ...ALAC_FILE_EXTENSIONS,
-  ...WEBM_FILE_EXTENSIONS
-];
-function isAudioFile(filenameOrExt) {
-  return AUDIO_FILE_EXTENSIONS.some((ext) => filenameOrExt.endsWith(ext));
-}
+import { MemoryAdapter } from "./adapters/memory.js";
+import { TmpFsAdapter as TmpFsAdapter2 } from "./adapters/tmpfs.js";
 class EpubVersionError extends Error {
 }
+class EpubReadOnlyError extends Error {
+}
 class Epub {
-  constructor(extractPath, inputPath) {
-    this.extractPath = extractPath;
+  /**
+   * Prefer the static factories ({@link Epub.using}, {@link Epub.from},
+   * {@link Epub.create}, {@link Epub.upgrade}) over calling this constructor
+   * directly. It's public so {@link EpubFactory} can construct instances; nothing
+   * else should need to.
+   */
+  constructor(adapterClass, adapter, inputPath, readonlyOverride = false) {
+    this.adapterClass = adapterClass;
+    this.adapter = adapter;
     this.inputPath = inputPath;
+    this.readonlyOverride = readonlyOverride;
+    this.storage = adapterClass.kind;
     this.readXhtmlItemContents = memoize(
       this.readXhtmlItemContents.bind(this),
       // This isn't unnecessary, the generic here just isn't handling the
@@ -242,86 +227,53 @@ ${JSON.stringify(element, null, 2)}`
   spine = null;
   packageMutex = new Mutex();
   /**
-   * Construct an Epub instance, optionally beginning
-   * with the provided metadata.
+   * Storage backend kind in use for this instance
    *
-   * @param dublinCore Core metadata terms
-   * @param additionalMetadata An array of additional metadata entries
+   * Public so callers can declare type-level requirements via {@link InMemoryEpubReader}
+   * Orthogonal to the read-only / writable axis (controlled by `readonlyOverride`
+   * and the adapter's capability bag)
    */
-  static async create(path, {
-    title,
-    language,
-    identifier,
-    date,
-    subjects,
-    type,
-    creators,
-    contributors
-  }, additionalMetadata = []) {
-    const extractPath = join(
-      tmpdir(),
-      `storyteller-platform-epub-${randomUUID()}`
-    );
-    const encoder = new TextEncoder();
-    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"/>
-  </rootfiles>
-</container>
-`);
-    await mkdir(join(extractPath, "META-INF"), { recursive: true });
-    await writeFile(join(extractPath, "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>
-  </metadata>
-  <manifest>
-  </manifest>
-  <spine>
-  </spine>
-</package>
-`);
-    await mkdir(join(extractPath, "OEBPS"));
-    await writeFile(join(extractPath, "OEBPS", "content.opf"), packageDocument);
-    const epub = new this(extractPath, path);
-    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))
+  storage;
+  /**
+   * Runtime guard for mutation methods
+   */
+  assertWritable() {
+    if (!this.adapterClass.capabilities.writable || this.readonlyOverride) {
+      throw new EpubReadOnlyError(
+        "cannot mutate a read-only Epub. open via Epub.using(TmpFsAdapter).from(path) (without { readonly: true }) to modify."
       );
     }
-    return epub;
   }
   /**
-   * Construct an Epub instance by reading an existing EPUB
-   * publication.
+   * Construct a new EPUB on a writable backend, optionally seeded
+   * with the provided metadata. Equivalent to
+   * `Epub.using(TmpFsAdapter).create(...)`.
    *
-   * @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.
+   * @param dublinCore Core metadata terms
+   * @param additionalMetadata An array of additional metadata entries
    */
-  static async from(pathOrData) {
-    const epub = await this.open(pathOrData);
+  static async create(path, dublinCore, additionalMetadata = []) {
+    return Epub.using(TmpFsAdapter).create(path, dublinCore, additionalMetadata);
+  }
+  /**
+   * Specify the storage backend to use for the EPUB
+   *
+   * The returned factory exposes `from`, `create`, and `upgrade`,
+   * which route through the supplied adapter.
+   *
+   * @example
+   * ```ts
+   * using epub = await Epub.using(TmpFsAdapter).from(path)
+   * using reader = await Epub.using(MemoryAdapter).from(buffer, { cache: false })
+   * ```
+   */
+  static using(adapterClass) {
+    return new EpubFactory(adapterClass);
+  }
+  static async from(pathOrData, options = {}) {
+    return Epub.using(TmpFsAdapter).from(pathOrData, options);
+  }
+  static async assertEpub3(epub) {
     const version = await epub.getVersion();
     if (!version.startsWith("3.")) {
       epub.discardAndClose();
@@ -329,85 +281,52 @@ ${JSON.stringify(element, null, 2)}`
         "This is not a valid EPUB 3 publication. This library only supports EPUB 3, not EPUB 2. Use Epub.upgrade(path) to convert."
       );
     }
-    return epub;
   }
-  /**
-   * Open an EPUB publication and return an Epub instance.
-   */
-  static async open(pathOrData) {
-    const extractPath = join(
-      tmpdir(),
-      `storyteller-platform-epub-${randomUUID()}.epub`
-    );
-    try {
-      var _stack = [];
-      try {
-        const zipfile = typeof pathOrData === "string" ? await open(pathOrData) : await fromBuffer(Buffer.from(pathOrData));
-        const stack = __using(_stack, new AsyncDisposableStack(), true);
-        stack.defer(async () => {
-          await zipfile.close();
-        });
-        for await (const entry of zipfile) {
-          if (entry.filename.endsWith("/")) {
-          } else {
-            const writePath = join(extractPath, entry.filename);
-            const readStream = await entry.openReadStream();
-            await mkdir(dirname(writePath), { recursive: true });
-            const writeStream = createWriteStream(writePath);
-            await pipeline(readStream, writeStream);
-          }
-        }
-      } catch (_) {
-        var _error = _, _hasError = true;
-      } finally {
-        var _promise = __callDispose(_stack, _error, _hasError);
-        _promise && await _promise;
-      }
-    } catch (error) {
-      rmSync(extractPath, { force: true, recursive: true });
-      throw error;
-    }
-    const epub = new this(
-      extractPath,
-      typeof pathOrData === "string" ? pathOrData : void 0
-    );
-    try {
-      await epub.getPackageElement();
-    } catch (e) {
-      epub.discardAndClose();
-      console.error(e);
+  async copy(path) {
+    if (!this.adapter.duplicate) {
       throw new Error(
-        "This is not a valid EPUB publication. Could not read the package document."
+        `cannot copy an Epub backed by ${this.adapterClass.kind}: adapter does not implement duplicate()`
       );
     }
-    return epub;
-  }
-  async copy(path) {
-    const extractPath = join(
-      tmpdir(),
-      `storyteller-platform-epub-${randomUUID()}.epub`
-    );
-    try {
-      await cp(this.extractPath, extractPath, { recursive: true });
-    } catch (error) {
-      rmSync(extractPath, { force: true, recursive: true });
-      throw error;
-    }
-    return new Epub(extractPath, path);
+    const newAdapter = await this.adapter.duplicate();
+    return new Epub(this.adapterClass, newAdapter, path);
   }
   async removeEntry(href) {
+    this.assertWritable();
+    if (!this.adapter.remove) {
+      throw new EpubReadOnlyError(
+        `adapter ${this.adapterClass.kind} does not support entry removal`
+      );
+    }
     const rootfile = await this.getRootfile();
     const filename = this.resolveInternalHref(rootfile, href);
-    await rm(filename);
+    await this.adapter.remove(filename);
   }
   async getFileData(path, encoding) {
-    return await readFile(path, encoding);
+    if (encoding) {
+      return this.adapter.read(path, encoding);
+    }
+    return this.adapter.read(path);
+  }
+  /**
+   * Length of the underlying archive entry for a manifest item, in bytes
+   * Necessary to compute the readium page count which is for COMPRESSED content
+   * @see {@link https://github.com/readium/architecture/issues/123}
+   */
+  async getItemArchiveLength(id) {
+    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.resolveInternalHref(rootfile, manifestItem.href);
+    return this.adapter.archiveLength(path);
   }
   async getRootfile() {
     var _a;
     if (this.rootfile !== null) return this.rootfile;
     const containerString = await this.getFileData(
-      join(this.extractPath, "META-INF", "container.xml"),
+      join(this.adapter.rootPath, "META-INF", "container.xml"),
       "utf-8"
     );
     if (!containerString)
@@ -439,7 +358,7 @@ ${JSON.stringify(element, null, 2)}`
       throw new Error(
         "Failed to parse EPUB container.xml: Found no rootfile element"
       );
-    this.rootfile = resolve(this.extractPath, fullPath);
+    this.rootfile = resolve(this.adapter.rootPath, fullPath);
     return this.rootfile;
   }
   async getPackageDocument() {
@@ -477,6 +396,7 @@ ${JSON.stringify(element, null, 2)}`
    *    it will be assumed that the package document was modified in place.
    */
   async withPackage(producer) {
+    this.assertWritable();
     await this.packageMutex.runExclusive(async () => {
       const packageDocument = await this.getPackageDocument();
       const packageElement = Epub.findXmlChildByName("package", packageDocument);
@@ -1710,7 +1630,11 @@ ${JSON.stringify(element, null, 2)}`
    */
   resolveInternalHref(from, href) {
     const startPath = dirname(from);
-    return resolve(this.extractPath, startPath, href);
+    return resolve(
+      this.adapter.rootPath,
+      hrefToPlatformPath(startPath),
+      hrefToPlatformPath(href)
+    );
   }
   /**
    * Returns a path-relative-scheme-less URL, relative to the
@@ -1724,7 +1648,7 @@ ${JSON.stringify(element, null, 2)}`
     const rootfile = await this.getRootfile();
     const from = relativeTo ? this.resolveInternalHref(rootfile, relativeTo) : rootfile;
     const path = this.resolveInternalHref(from, href);
-    return path.replace(toRoot ? this.extractPath : dirname(rootfile), "").slice(1);
+    return path.replace(toRoot ? this.adapter.rootPath : dirname(rootfile), "").slice(1);
   }
   async readFileContents(href, relativeTo, encoding) {
     const rootfile = await this.getRootfile();
@@ -1779,8 +1703,17 @@ ${JSON.stringify(element, null, 2)}`
     return Epub.getXhtmlTextContent(body);
   }
   async writeEntryContents(path, contents, encoding) {
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, contents, encoding);
+    this.assertWritable();
+    if (!this.adapter.write) {
+      throw new EpubReadOnlyError(
+        `adapter ${this.adapterClass.kind} does not support writes`
+      );
+    }
+    if (encoding === "utf-8") {
+      await this.adapter.write(path, contents, encoding);
+    } else {
+      await this.adapter.write(path, contents);
+    }
   }
   async writeItemContents(id, contents, encoding) {
     const rootfile = await this.getRootfile();
@@ -1870,8 +1803,7 @@ ${JSON.stringify(element, null, 2)}`
         contents
       )
     ) : contents;
-    await mkdir(dirname(filename), { recursive: true });
-    await writeFile(filename, data);
+    await this.writeEntryContents(filename, data);
   }
   /**
    * Update the manifest entry for an existing item.
@@ -2124,7 +2056,7 @@ ${JSON.stringify(element, null, 2)}`
     this.rootfile = null;
     this.manifest = null;
     this.spine = null;
-    rmSync(this.extractPath, { recursive: true, force: true });
+    void this.adapter.dispose();
   }
   /**
    * Write the current contents of the Epub to a new
@@ -2135,63 +2067,157 @@ ${JSON.stringify(element, null, 2)}`
    * timestamp.
    */
   async saveAndClose() {
-    var _stack = [];
-    try {
-      if (!this.inputPath) {
-        throw new Error("In-memory EPUB files cannot be saved to disk");
+    this.assertWritable();
+    if (!this.inputPath) {
+      throw new Error("In-memory EPUB files cannot be saved to disk");
+    }
+    if (!this.adapter.serialize) {
+      throw new Error(
+        `adapter ${this.adapterClass.kind} does not support serialization`
+      );
+    }
+    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+/, "")
       }
-      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+/, "")
-        }
+    );
+    await this.adapter.serialize(this.inputPath);
+  }
+  /**
+   * Upgrade an EPUB 2 publication to EPUB 3 in place, returning a new,
+   * valid Epub 3 instance. Equivalent to
+   * `Epub.using(TmpFsAdapter).upgrade(...)`.
+   */
+  static async upgrade(path, options = {}) {
+    return Epub.using(TmpFsAdapter).upgrade(path, options);
+  }
+  [Symbol.dispose]() {
+    this.discardAndClose();
+  }
+}
+class EpubFactory {
+  constructor(adapterClass) {
+    this.adapterClass = adapterClass;
+  }
+  async from(source, options = {}) {
+    const adapter = await this.adapterClass.init(
+      source,
+      options
+    );
+    const inputPath = typeof source === "string" ? source : void 0;
+    const readonlyOverride = options.readonly === true;
+    const epub = new Epub(
+      this.adapterClass,
+      adapter,
+      inputPath,
+      readonlyOverride
+    );
+    try {
+      await epub.getPackageElement();
+    } catch (e) {
+      epub.discardAndClose();
+      console.error(e);
+      throw new Error(
+        "This is not a valid EPUB publication. Could not read the package document."
+      );
+    }
+    await Epub.assertEpub3(epub);
+    return epub;
+  }
+  /**
+   * Construct a new EPUB on this factory's adapter, optionally seeded
+   * with the provided metadata. Requires a writable adapter that
+   * implements `initEmpty` (today: {@link TmpFsAdapter}).
+   *
+   * @throws when the adapter is read-only or does not implement initEmpty
+   */
+  async create(path, {
+    title,
+    language,
+    identifier,
+    date,
+    subjects,
+    type,
+    creators,
+    contributors
+  }, additionalMetadata = []) {
+    if (!this.adapterClass.capabilities.writable) {
+      throw new EpubReadOnlyError(
+        `adapter ${this.adapterClass.kind} is read-only; cannot create`
       );
-      const tmpArchivePath = join(
-        tmpdir(),
-        `storyteller-platform-epub-${randomUUID()}`
+    }
+    if (!this.adapterClass.initEmpty) {
+      throw new Error(
+        `adapter ${this.adapterClass.kind} does not support create() (missing initEmpty)`
       );
-      const { promise, resolve: resolve2 } = Promise.withResolvers();
-      const zipfile = new ZipFile();
-      const writeStream = createWriteStream(tmpArchivePath);
-      writeStream.on("close", () => {
-        resolve2();
-      });
-      const stack = __using(_stack, new AsyncDisposableStack(), true);
-      stack.defer(async () => {
-        writeStream.close();
-        await rm(tmpArchivePath, { force: true });
-      });
-      zipfile.outputStream.pipe(writeStream);
-      zipfile.addBuffer(Buffer.from("application/epub+zip"), "mimetype", {
-        compress: false
-      });
-      const entries = await readdir(this.extractPath, {
-        recursive: true,
-        withFileTypes: true
-      });
-      for (const entry of entries) {
-        if (entry.name === "mimetype" || entry.isDirectory()) continue;
-        zipfile.addFile(
-          join(entry.parentPath, entry.name),
-          join(entry.parentPath, entry.name).replace(`${this.extractPath}/`, ""),
-          { compress: !isAudioFile(entry.name) }
-        );
-      }
-      zipfile.end();
-      await promise;
-      await cp(tmpArchivePath, this.inputPath);
-    } catch (_) {
-      var _error = _, _hasError = true;
-    } finally {
-      var _promise = __callDispose(_stack, _error, _hasError);
-      _promise && await _promise;
     }
+    const adapter = await this.adapterClass.initEmpty();
+    if (!adapter.write) {
+      throw new Error(
+        `adapter ${this.adapterClass.kind} declared writable but did not implement write()`
+      );
+    }
+    const encoder = new TextEncoder();
+    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"/>
+  </rootfiles>
+</container>
+`);
+    await adapter.write(
+      join(adapter.rootPath, "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>
+  </metadata>
+  <manifest>
+  </manifest>
+  <spine>
+  </spine>
+</package>
+`);
+    await adapter.write(
+      join(adapter.rootPath, "OEBPS", "content.opf"),
+      packageDocument
+    );
+    const epub = new Epub(this.adapterClass, adapter, path);
+    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;
   }
   /**
-   * Upgrade an EPUB 2 publication to EPUB 3 in place, returning a new, valid Epub 3 instance.
+   * Upgrade an EPUB 2 publication to EPUB 3 in place using this
+   * factory's adapter, returning a new, valid Epub 3 instance.
    *
    * Performs the following transformations:
    *  - upgrades OPF metadata to EPUB 3 conventions
@@ -2201,15 +2227,40 @@ ${JSON.stringify(element, null, 2)}`
    *  - fixes common font MIME types
    *  - bumps the package version to 3.0
    *  - goes over each xhtml item and rewrites it using XMLParser to make sure the output is valid XHTML
+   *
+   * Requires a writable adapter. When {@link Upgrade.Epub2UpgradeOptions.outputPath}
+   * is set, the source file is copied to that path on disk first; this
+   * only makes sense for adapters whose `source` is a real fs path.
+   *
+   * @throws when the adapter is read-only
    */
-  static async upgrade(path, options = {}) {
+  async upgrade(path, options = {}) {
     var _a;
+    if (!this.adapterClass.capabilities.writable) {
+      throw new EpubReadOnlyError(
+        `adapter ${this.adapterClass.kind} is read-only; cannot upgrade`
+      );
+    }
     const { removeNcx = false, outputPath } = options;
     if (outputPath) {
       await mkdir(dirname(outputPath), { recursive: true });
       await cp(path, outputPath, { force: true });
     }
-    const epub = await Epub.open(outputPath ?? path);
+    const source = outputPath ?? path;
+    const adapter = await this.adapterClass.init(
+      source,
+      options
+    );
+    const epub = new Epub(this.adapterClass, adapter, source);
+    try {
+      await epub.getPackageElement();
+    } catch (e) {
+      epub.discardAndClose();
+      console.error(e);
+      throw new Error(
+        "This is not a valid EPUB publication. Could not read the package document."
+      );
+    }
     const version = await epub.getVersion();
     if (version.startsWith("3.")) {
       return epub;
@@ -2254,11 +2305,12 @@ ${JSON.stringify(element, null, 2)}`
     }
     return epub;
   }
-  [Symbol.dispose]() {
-    this.discardAndClose();
-  }
 }
 export {
   Epub,
-  EpubVersionError
+  EpubFactory,
+  EpubReadOnlyError,
+  EpubVersionError,
+  MemoryAdapter,
+  TmpFsAdapter2 as TmpFsAdapter
 };