@storyteller-platform/epub 0.5.1 → 0.6.1

package/dist/index.cjs

@@ -5,10 +5,6 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : Symbol.for("Symbol." + name);
-var __typeError = (msg) => {
-  throw TypeError(msg);
-};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -30,98 +26,44 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __using = (stack, value, async) => {
-  if (value != null) {
-    if (typeof value !== "object" && typeof value !== "function") __typeError("Object expected");
-    var dispose, inner;
-    if (async) dispose = value[__knownSymbol("asyncDispose")];
-    if (dispose === void 0) {
-      dispose = value[__knownSymbol("dispose")];
-      if (async) inner = dispose;
-    }
-    if (typeof dispose !== "function") __typeError("Object not disposable");
-    if (inner) dispose = function() {
-      try {
-        inner.call(this);
-      } catch (e) {
-        return Promise.reject(e);
-      }
-    };
-    stack.push([async, dispose, value]);
-  } else if (async) {
-    stack.push([async]);
-  }
-  return value;
-};
-var __callDispose = (stack, error, hasError) => {
-  var E = typeof SuppressedError === "function" ? SuppressedError : function(e, s, m, _) {
-    return _ = Error(m), _.name = "SuppressedError", _.error = e, _.suppressed = s, _;
-  };
-  var fail = (e) => error = hasError ? new E(e, error, "An error was suppressed during disposal") : (hasError = true, e);
-  var next = (it) => {
-    while (it = stack.pop()) {
-      try {
-        var result = it[1] && it[1].call(it[2]);
-        if (it[0]) return Promise.resolve(result).then(next, (e) => (fail(e), next()));
-      } catch (e) {
-        fail(e);
-      }
-    }
-    if (hasError) throw error;
-  };
-  return next();
-};
 var index_exports = {};
 __export(index_exports, {
   Epub: () => Epub,
-  EpubVersionError: () => EpubVersionError
+  EpubFactory: () => EpubFactory,
+  EpubReadOnlyError: () => EpubReadOnlyError,
+  EpubVersionError: () => EpubVersionError,
+  MemoryAdapter: () => import_memory.MemoryAdapter,
+  TmpFsAdapter: () => import_tmpfs2.TmpFsAdapter
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_crypto = require("node:crypto");
-var import_node_fs = require("node:fs");
 var import_promises = require("node:fs/promises");
-var import_node_os = require("node:os");
-var import_promises2 = require("node:stream/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_yauzl_promise = require("yauzl-promise");
-var import_yazl = require("yazl");
 var import_path = require("@storyteller-platform/path");
+var import_tmpfs = require("./adapters/tmpfs.cjs");
 var Upgrade = __toESM(require("./upgrade.ts"), 1);
-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));
-}
+var import_memory = require("./adapters/memory.cjs");
+var import_tmpfs2 = require("./adapters/tmpfs.cjs");
 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 = (0, import_mem.default)(
       this.readXhtmlItemContents.bind(this),
       // This isn't unnecessary, the generic here just isn't handling the
@@ -317,86 +259,53 @@ ${JSON.stringify(element, null, 2)}`
   spine = null;
   packageMutex = new import_async_mutex.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 = (0, import_path.join)(
-      (0, import_node_os.tmpdir)(),
-      `storyteller-platform-epub-${(0, import_node_crypto.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 (0, import_promises.mkdir)((0, import_path.join)(extractPath, "META-INF"), { recursive: true });
-    await (0, import_promises.writeFile)((0, import_path.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 (0, import_promises.mkdir)((0, import_path.join)(extractPath, "OEBPS"));
-    await (0, import_promises.writeFile)((0, import_path.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 dublinCore Core metadata terms
+   * @param additionalMetadata An array of additional metadata entries
+   */
+  static async create(path, dublinCore, additionalMetadata = []) {
+    return Epub.using(import_tmpfs.TmpFsAdapter).create(path, dublinCore, additionalMetadata);
+  }
+  /**
+   * Specify the storage backend to use for the EPUB
    *
-   * @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.
+   * 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 async from(pathOrData) {
-    const epub = await this.open(pathOrData);
+  static using(adapterClass) {
+    return new EpubFactory(adapterClass);
+  }
+  static async from(pathOrData, options = {}) {
+    return Epub.using(import_tmpfs.TmpFsAdapter).from(pathOrData, options);
+  }
+  static async assertEpub3(epub) {
     const version = await epub.getVersion();
     if (!version.startsWith("3.")) {
       epub.discardAndClose();
@@ -404,85 +313,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 = (0, import_path.join)(
-      (0, import_node_os.tmpdir)(),
-      `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}.epub`
-    );
-    try {
-      var _stack = [];
-      try {
-        const zipfile = typeof pathOrData === "string" ? await (0, import_yauzl_promise.open)(pathOrData) : await (0, import_yauzl_promise.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(import_path.sep)) {
-          } else {
-            const writePath = (0, import_path.join)(extractPath, entry.filename);
-            const readStream = await entry.openReadStream();
-            await (0, import_promises.mkdir)((0, import_path.dirname)(writePath), { recursive: true });
-            const writeStream = (0, import_node_fs.createWriteStream)(writePath);
-            await (0, import_promises2.pipeline)(readStream, writeStream);
-          }
-        }
-      } catch (_) {
-        var _error = _, _hasError = true;
-      } finally {
-        var _promise = __callDispose(_stack, _error, _hasError);
-        _promise && await _promise;
-      }
-    } catch (error) {
-      (0, import_node_fs.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 = (0, import_path.join)(
-      (0, import_node_os.tmpdir)(),
-      `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}.epub`
-    );
-    try {
-      await (0, import_promises.cp)(this.extractPath, extractPath, { recursive: true });
-    } catch (error) {
-      (0, import_node_fs.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 (0, import_promises.rm)(filename);
+    await this.adapter.remove(filename);
   }
   async getFileData(path, encoding) {
-    return await (0, import_promises.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(
-      (0, import_path.join)(this.extractPath, "META-INF", "container.xml"),
+      (0, import_path.join)(this.adapter.rootPath, "META-INF", "container.xml"),
       "utf-8"
     );
     if (!containerString)
@@ -514,7 +390,7 @@ ${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.extractPath, fullPath);
+    this.rootfile = (0, import_path.resolve)(this.adapter.rootPath, fullPath);
     return this.rootfile;
   }
   async getPackageDocument() {
@@ -552,6 +428,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);
@@ -1786,7 +1663,7 @@ ${JSON.stringify(element, null, 2)}`
   resolveInternalHref(from, href) {
     const startPath = (0, import_path.dirname)(from);
     return (0, import_path.resolve)(
-      this.extractPath,
+      this.adapter.rootPath,
       (0, import_path.hrefToPlatformPath)(startPath),
       (0, import_path.hrefToPlatformPath)(href)
     );
@@ -1803,7 +1680,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 : (0, import_path.dirname)(rootfile), "").slice(1);
+    return path.replace(toRoot ? this.adapter.rootPath : (0, import_path.dirname)(rootfile), "").slice(1);
   }
   async readFileContents(href, relativeTo, encoding) {
     const rootfile = await this.getRootfile();
@@ -1858,8 +1735,17 @@ ${JSON.stringify(element, null, 2)}`
     return Epub.getXhtmlTextContent(body);
   }
   async writeEntryContents(path, contents, encoding) {
-    await (0, import_promises.mkdir)((0, import_path.dirname)(path), { recursive: true });
-    await (0, import_promises.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();
@@ -1949,8 +1835,7 @@ ${JSON.stringify(element, null, 2)}`
         contents
       )
     ) : contents;
-    await (0, import_promises.mkdir)((0, import_path.dirname)(filename), { recursive: true });
-    await (0, import_promises.writeFile)(filename, data);
+    await this.writeEntryContents(filename, data);
   }
   /**
    * Update the manifest entry for an existing item.
@@ -2203,7 +2088,7 @@ ${JSON.stringify(element, null, 2)}`
     this.rootfile = null;
     this.manifest = null;
     this.spine = null;
-    (0, import_node_fs.rmSync)(this.extractPath, { recursive: true, force: true });
+    void this.adapter.dispose();
   }
   /**
    * Write the current contents of the Epub to a new
@@ -2214,63 +2099,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(import_tmpfs.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`
+      );
+    }
+    if (!this.adapterClass.initEmpty) {
+      throw new Error(
+        `adapter ${this.adapterClass.kind} does not support create() (missing initEmpty)`
       );
-      const tmpArchivePath = (0, import_path.join)(
-        (0, import_node_os.tmpdir)(),
-        `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}`
+    }
+    const adapter = await this.adapterClass.initEmpty();
+    if (!adapter.write) {
+      throw new Error(
+        `adapter ${this.adapterClass.kind} declared writable but did not implement write()`
       );
-      const { promise, resolve: resolve2 } = Promise.withResolvers();
-      const zipfile = new import_yazl.ZipFile();
-      const writeStream = (0, import_node_fs.createWriteStream)(tmpArchivePath);
-      writeStream.on("close", () => {
-        resolve2();
-      });
-      const stack = __using(_stack, new AsyncDisposableStack(), true);
-      stack.defer(async () => {
-        writeStream.close();
-        await (0, import_promises.rm)(tmpArchivePath, { force: true });
-      });
-      zipfile.outputStream.pipe(writeStream);
-      zipfile.addBuffer(Buffer.from("application/epub+zip"), "mimetype", {
-        compress: false
-      });
-      const entries = await (0, import_promises.readdir)(this.extractPath, {
-        recursive: true,
-        withFileTypes: true
-      });
-      for (const entry of entries) {
-        if (entry.name === "mimetype" || entry.isDirectory()) continue;
-        zipfile.addFile(
-          (0, import_path.join)(entry.parentPath, entry.name),
-          (0, import_path.join)(entry.parentPath, entry.name).replace(`${this.extractPath}/`, ""),
-          { compress: !isAudioFile(entry.name) }
-        );
-      }
-      zipfile.end();
-      await promise;
-      await (0, import_promises.cp)(tmpArchivePath, this.inputPath);
-    } catch (_) {
-      var _error = _, _hasError = true;
-    } finally {
-      var _promise = __callDispose(_stack, _error, _hasError);
-      _promise && await _promise;
     }
+    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(
+      (0, import_path.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(
+      (0, import_path.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
@@ -2280,15 +2259,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 (0, import_promises.mkdir)((0, import_path.dirname)(outputPath), { recursive: true });
       await (0, import_promises.cp)(path, outputPath, { force: true });
     }
-    const epub = await Epub.open(outputPath ?? path);
+    const 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;
@@ -2333,12 +2337,13 @@ ${JSON.stringify(element, null, 2)}`
     }
     return epub;
   }
-  [Symbol.dispose]() {
-    this.discardAndClose();
-  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Epub,
-  EpubVersionError
+  EpubFactory,
+  EpubReadOnlyError,
+  EpubVersionError,
+  MemoryAdapter,
+  TmpFsAdapter
 });