@storyteller-platform/epub 0.5.1 → 0.6.1

package/dist/adapters/interface.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var interface_exports = {};
+module.exports = __toCommonJS(interface_exports);

package/dist/adapters/interface.d.cts

@@ -0,0 +1,69 @@
+/**
+ * Pluggable storage backend for an Epub instance
+ *
+ * Built-in adapters:
+ *  - {@link TmpFsAdapter} extracts the archive to a tmp directory and
+ *    supports the full read/write/save/upgrade
+ *  - {@link MemoryAdapter} keeps an in-memory zip handle and supports
+ *    reads only
+ */
+type EpubStorageKind = "tmp-dir" | "in-memory" | (string & {});
+interface EpubStorageCapabilities {
+    /** when false, the Epub class refuses every mutation method at runtime */
+    readonly writable: boolean;
+}
+interface EpubListEntry {
+    /** absolute path under {@link EpubStorageAdapter.rootPath} */
+    absolutePath: string;
+    /** path relative to {@link EpubStorageAdapter.rootPath}, slash-separated */
+    relativePath: string;
+}
+interface EpubStorageAdapter {
+    /**
+     * Opaque path prefix used by `resolveInternalHref` to anchor absolute
+     * paths within the archive. For TmpFsAdapter this is the tmp dir;
+     * for MemoryAdapter it's a virtual prefix that's never written to disk
+     */
+    readonly rootPath: string;
+    read(path: string): Promise<Uint8Array>;
+    read(path: string, encoding: "utf-8"): Promise<string>;
+    /**
+     * Length of an entry in bytes, for the readium page-count heuristic
+     * which expects compressed size when available
+     */
+    archiveLength(path: string): Promise<number>;
+    /** Required for any mutation method on Epub */
+    write?(path: string, data: Uint8Array): Promise<void>;
+    write?(path: string, data: string, encoding: "utf-8"): Promise<void>;
+    /** Required for removeManifestItem / setCoverImage replacement */
+    remove?(path: string): Promise<void>;
+    /** Required for Epub.saveAndClose to walk the contents */
+    list?(): AsyncIterable<EpubListEntry>;
+    /** Required for Epub.copy */
+    duplicate?(): Promise<EpubStorageAdapter>;
+    /** Required for Epub.saveAndClose */
+    serialize?(targetPath: string): Promise<void>;
+    /** Always called on close or error */
+    dispose(): void | Promise<void>;
+}
+interface EpubStorageAdapterClass<Opts extends object = object> {
+    readonly kind: EpubStorageKind;
+    readonly capabilities: EpubStorageCapabilities;
+    /**
+     * Open an archive from a path or buffer. The returned adapter is
+     * ready to read; the Epub class will assert it's a valid EPUB 3
+     * afterwards.
+     */
+    init(source: string | Uint8Array, opts?: Opts): Promise<EpubStorageAdapter>;
+    /**
+     * Initialize an empty extract root for {@link Epub.create}.
+     *
+     * Optional — adapters that can't be written to from scratch
+     * (e.g. read-only zip handles) should leave this off, and
+     * `Epub.using(...).create(...)` will throw.
+     */
+    initEmpty?(opts?: Opts): Promise<EpubStorageAdapter>;
+}
+type AdapterOptions<A> = A extends EpubStorageAdapterClass<infer Opts> ? Opts : object;
+
+export type { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind };

package/dist/adapters/interface.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pluggable storage backend for an Epub instance
+ *
+ * Built-in adapters:
+ *  - {@link TmpFsAdapter} extracts the archive to a tmp directory and
+ *    supports the full read/write/save/upgrade
+ *  - {@link MemoryAdapter} keeps an in-memory zip handle and supports
+ *    reads only
+ */
+type EpubStorageKind = "tmp-dir" | "in-memory" | (string & {});
+interface EpubStorageCapabilities {
+    /** when false, the Epub class refuses every mutation method at runtime */
+    readonly writable: boolean;
+}
+interface EpubListEntry {
+    /** absolute path under {@link EpubStorageAdapter.rootPath} */
+    absolutePath: string;
+    /** path relative to {@link EpubStorageAdapter.rootPath}, slash-separated */
+    relativePath: string;
+}
+interface EpubStorageAdapter {
+    /**
+     * Opaque path prefix used by `resolveInternalHref` to anchor absolute
+     * paths within the archive. For TmpFsAdapter this is the tmp dir;
+     * for MemoryAdapter it's a virtual prefix that's never written to disk
+     */
+    readonly rootPath: string;
+    read(path: string): Promise<Uint8Array>;
+    read(path: string, encoding: "utf-8"): Promise<string>;
+    /**
+     * Length of an entry in bytes, for the readium page-count heuristic
+     * which expects compressed size when available
+     */
+    archiveLength(path: string): Promise<number>;
+    /** Required for any mutation method on Epub */
+    write?(path: string, data: Uint8Array): Promise<void>;
+    write?(path: string, data: string, encoding: "utf-8"): Promise<void>;
+    /** Required for removeManifestItem / setCoverImage replacement */
+    remove?(path: string): Promise<void>;
+    /** Required for Epub.saveAndClose to walk the contents */
+    list?(): AsyncIterable<EpubListEntry>;
+    /** Required for Epub.copy */
+    duplicate?(): Promise<EpubStorageAdapter>;
+    /** Required for Epub.saveAndClose */
+    serialize?(targetPath: string): Promise<void>;
+    /** Always called on close or error */
+    dispose(): void | Promise<void>;
+}
+interface EpubStorageAdapterClass<Opts extends object = object> {
+    readonly kind: EpubStorageKind;
+    readonly capabilities: EpubStorageCapabilities;
+    /**
+     * Open an archive from a path or buffer. The returned adapter is
+     * ready to read; the Epub class will assert it's a valid EPUB 3
+     * afterwards.
+     */
+    init(source: string | Uint8Array, opts?: Opts): Promise<EpubStorageAdapter>;
+    /**
+     * Initialize an empty extract root for {@link Epub.create}.
+     *
+     * Optional — adapters that can't be written to from scratch
+     * (e.g. read-only zip handles) should leave this off, and
+     * `Epub.using(...).create(...)` will throw.
+     */
+    initEmpty?(opts?: Opts): Promise<EpubStorageAdapter>;
+}
+type AdapterOptions<A> = A extends EpubStorageAdapterClass<infer Opts> ? Opts : object;
+
+export type { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind };

package/dist/adapters/memory.cjs

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var memory_exports = {};
+__export(memory_exports, {
+  MemoryAdapter: () => MemoryAdapter
+});
+module.exports = __toCommonJS(memory_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_os = require("node:os");
+var import_yauzl_promise = require("yauzl-promise");
+var import_path = require("@storyteller-platform/path");
+class MemoryAdapter {
+  constructor(rootPath, zip, entries, cache) {
+    this.rootPath = rootPath;
+    this.zip = zip;
+    this.entries = entries;
+    this.cache = cache;
+  }
+  static kind = "in-memory";
+  static capabilities = { writable: false };
+  static async init(source, opts = {}) {
+    const { cache = true, signal } = opts;
+    signal == null ? void 0 : signal.throwIfAborted();
+    const zip = typeof source === "string" ? await (0, import_yauzl_promise.open)(source) : await (0, import_yauzl_promise.fromBuffer)(Buffer.from(source));
+    const entries = /* @__PURE__ */ new Map();
+    try {
+      for await (const entry of zip) {
+        signal == null ? void 0 : signal.throwIfAborted();
+        if (entry.filename.endsWith("/")) continue;
+        entries.set(entry.filename, entry);
+      }
+    } catch (error) {
+      await zip.close();
+      throw error;
+    }
+    const rootPath = (0, import_path.join)(
+      (0, import_node_os.tmpdir)(),
+      `storyteller-platform-epub-zip-${(0, import_node_crypto.randomUUID)()}.epub`
+    );
+    return new MemoryAdapter(rootPath, zip, entries, cache ? /* @__PURE__ */ new Map() : null);
+  }
+  toZipEntryKey(path) {
+    const prefix = this.rootPath.endsWith(import_path.sep) ? this.rootPath : this.rootPath + import_path.sep;
+    const rel = path.startsWith(prefix) ? path.slice(prefix.length) : path;
+    return import_path.sep === "/" ? rel : rel.split(import_path.sep).join("/");
+  }
+  async read(path, encoding) {
+    var _a, _b;
+    const key = this.toZipEntryKey(path);
+    const cached = (_a = this.cache) == null ? void 0 : _a.get(key);
+    if (cached) {
+      return encoding ? cached.toString(encoding) : new Uint8Array(cached);
+    }
+    const entry = this.entries.get(key);
+    if (!entry) {
+      const err = new Error(
+        `ENOENT: zip entry not found in EPUB archive: ${key}`
+      );
+      err.code = "ENOENT";
+      throw err;
+    }
+    const stream = await entry.openReadStream();
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+    const buf = Buffer.concat(chunks);
+    (_b = this.cache) == null ? void 0 : _b.set(key, buf);
+    return encoding ? buf.toString(encoding) : new Uint8Array(buf);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async archiveLength(path) {
+    const entry = this.entries.get(this.toZipEntryKey(path));
+    if (!entry) return 0;
+    return entry.compressedSize || entry.uncompressedSize;
+  }
+  dispose() {
+    var _a;
+    this.entries.clear();
+    (_a = this.cache) == null ? void 0 : _a.clear();
+    this.zip.close().catch(() => void 0);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryAdapter
+});

package/dist/adapters/memory.d.cts

@@ -0,0 +1,37 @@
+import { EpubStorageAdapter } from './interface.cjs';
+
+interface MemoryAdapterOptions {
+    /**
+     * per-entry decompressed buffer cache
+     * turn it off when opening many EPUBs and reading each entry at most once
+     * keeps resident size bounded by the entry index, not the decompressed payload sum
+     * @default true
+     */
+    cache?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Loads an EPUB archive into memory and serves all I/O off the in-memory zip handle.
+ *
+ * read only
+ *
+ */
+declare class MemoryAdapter implements EpubStorageAdapter {
+    readonly rootPath: string;
+    private zip;
+    private entries;
+    private cache;
+    static readonly kind: "in-memory";
+    static readonly capabilities: {
+        readonly writable: false;
+    };
+    static init(source: string | Uint8Array, opts?: MemoryAdapterOptions): Promise<MemoryAdapter>;
+    private constructor();
+    private toZipEntryKey;
+    read(path: string): Promise<Uint8Array>;
+    read(path: string, encoding: "utf-8"): Promise<string>;
+    archiveLength(path: string): Promise<number>;
+    dispose(): void;
+}
+
+export { MemoryAdapter, type MemoryAdapterOptions };

package/dist/adapters/memory.d.ts

@@ -0,0 +1,37 @@
+import { EpubStorageAdapter } from './interface.js';
+
+interface MemoryAdapterOptions {
+    /**
+     * per-entry decompressed buffer cache
+     * turn it off when opening many EPUBs and reading each entry at most once
+     * keeps resident size bounded by the entry index, not the decompressed payload sum
+     * @default true
+     */
+    cache?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Loads an EPUB archive into memory and serves all I/O off the in-memory zip handle.
+ *
+ * read only
+ *
+ */
+declare class MemoryAdapter implements EpubStorageAdapter {
+    readonly rootPath: string;
+    private zip;
+    private entries;
+    private cache;
+    static readonly kind: "in-memory";
+    static readonly capabilities: {
+        readonly writable: false;
+    };
+    static init(source: string | Uint8Array, opts?: MemoryAdapterOptions): Promise<MemoryAdapter>;
+    private constructor();
+    private toZipEntryKey;
+    read(path: string): Promise<Uint8Array>;
+    read(path: string, encoding: "utf-8"): Promise<string>;
+    archiveLength(path: string): Promise<number>;
+    dispose(): void;
+}
+
+export { MemoryAdapter, type MemoryAdapterOptions };

package/dist/adapters/memory.js

@@ -0,0 +1,83 @@
+import "../chunk-BIEQXUOY.js";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import {
+  fromBuffer,
+  open
+} from "yauzl-promise";
+import { join, sep } from "@storyteller-platform/path";
+class MemoryAdapter {
+  constructor(rootPath, zip, entries, cache) {
+    this.rootPath = rootPath;
+    this.zip = zip;
+    this.entries = entries;
+    this.cache = cache;
+  }
+  static kind = "in-memory";
+  static capabilities = { writable: false };
+  static async init(source, opts = {}) {
+    const { cache = true, signal } = opts;
+    signal == null ? void 0 : signal.throwIfAborted();
+    const zip = typeof source === "string" ? await open(source) : await fromBuffer(Buffer.from(source));
+    const entries = /* @__PURE__ */ new Map();
+    try {
+      for await (const entry of zip) {
+        signal == null ? void 0 : signal.throwIfAborted();
+        if (entry.filename.endsWith("/")) continue;
+        entries.set(entry.filename, entry);
+      }
+    } catch (error) {
+      await zip.close();
+      throw error;
+    }
+    const rootPath = join(
+      tmpdir(),
+      `storyteller-platform-epub-zip-${randomUUID()}.epub`
+    );
+    return new MemoryAdapter(rootPath, zip, entries, cache ? /* @__PURE__ */ new Map() : null);
+  }
+  toZipEntryKey(path) {
+    const prefix = this.rootPath.endsWith(sep) ? this.rootPath : this.rootPath + sep;
+    const rel = path.startsWith(prefix) ? path.slice(prefix.length) : path;
+    return sep === "/" ? rel : rel.split(sep).join("/");
+  }
+  async read(path, encoding) {
+    var _a, _b;
+    const key = this.toZipEntryKey(path);
+    const cached = (_a = this.cache) == null ? void 0 : _a.get(key);
+    if (cached) {
+      return encoding ? cached.toString(encoding) : new Uint8Array(cached);
+    }
+    const entry = this.entries.get(key);
+    if (!entry) {
+      const err = new Error(
+        `ENOENT: zip entry not found in EPUB archive: ${key}`
+      );
+      err.code = "ENOENT";
+      throw err;
+    }
+    const stream = await entry.openReadStream();
+    const chunks = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+    const buf = Buffer.concat(chunks);
+    (_b = this.cache) == null ? void 0 : _b.set(key, buf);
+    return encoding ? buf.toString(encoding) : new Uint8Array(buf);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async archiveLength(path) {
+    const entry = this.entries.get(this.toZipEntryKey(path));
+    if (!entry) return 0;
+    return entry.compressedSize || entry.uncompressedSize;
+  }
+  dispose() {
+    var _a;
+    this.entries.clear();
+    (_a = this.cache) == null ? void 0 : _a.clear();
+    this.zip.close().catch(() => void 0);
+  }
+}
+export {
+  MemoryAdapter
+};

package/dist/adapters/tmpfs.cjs

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+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 tmpfs_exports = {};
+__export(tmpfs_exports, {
+  TmpFsAdapter: () => TmpFsAdapter
+});
+module.exports = __toCommonJS(tmpfs_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_yauzl_promise = require("yauzl-promise");
+var import_yazl = require("yazl");
+var import_path = require("@storyteller-platform/path");
+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));
+}
+function mintRootPath() {
+  return (0, import_path.join)((0, import_node_os.tmpdir)(), `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}`);
+}
+class TmpFsAdapter {
+  constructor(rootPath) {
+    this.rootPath = rootPath;
+  }
+  static kind = "extracted-dir";
+  static capabilities = { writable: true };
+  static async init(source) {
+    const rootPath = mintRootPath();
+    try {
+      var _stack = [];
+      try {
+        const zipfile = typeof source === "string" ? await (0, import_yauzl_promise.open)(source) : await (0, import_yauzl_promise.fromBuffer)(Buffer.from(source));
+        const stack = __using(_stack, new AsyncDisposableStack(), true);
+        stack.defer(async () => {
+          await zipfile.close();
+        });
+        for await (const entry of zipfile) {
+          if (entry.filename.endsWith("/")) {
+            continue;
+          }
+          const writePath = (0, import_path.join)(rootPath, 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)(rootPath, { force: true, recursive: true });
+      throw error;
+    }
+    return new TmpFsAdapter(rootPath);
+  }
+  static async initEmpty() {
+    const rootPath = mintRootPath();
+    await (0, import_promises.mkdir)(rootPath, { recursive: true });
+    return new TmpFsAdapter(rootPath);
+  }
+  async read(path, encoding) {
+    return await (0, import_promises.readFile)(path, encoding);
+  }
+  async write(path, data, encoding) {
+    await (0, import_promises.mkdir)((0, import_path.dirname)(path), { recursive: true });
+    await (0, import_promises.writeFile)(path, data, encoding);
+  }
+  async remove(path) {
+    await (0, import_promises.rm)(path);
+  }
+  async archiveLength(path) {
+    try {
+      const st = await (0, import_promises.stat)(path);
+      return st.size;
+    } catch {
+      return 0;
+    }
+  }
+  async *list() {
+    const entries = await (0, import_promises.readdir)(this.rootPath, {
+      recursive: true,
+      withFileTypes: true
+    });
+    for (const entry of entries) {
+      if (entry.isDirectory()) continue;
+      const absolutePath = (0, import_path.join)(entry.parentPath, entry.name);
+      yield {
+        absolutePath,
+        relativePath: absolutePath.replace(`${this.rootPath}${import_path.sep}`, "")
+      };
+    }
+  }
+  async duplicate() {
+    const newRoot = mintRootPath();
+    try {
+      await (0, import_promises.cp)(this.rootPath, newRoot, { recursive: true });
+    } catch (error) {
+      (0, import_node_fs.rmSync)(newRoot, { force: true, recursive: true });
+      throw error;
+    }
+    return new TmpFsAdapter(newRoot);
+  }
+  async serialize(targetPath) {
+    var _stack = [];
+    try {
+      const tmpArchivePath = (0, import_path.join)(
+        (0, import_node_os.tmpdir)(),
+        `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}`
+      );
+      const { promise, resolve } = Promise.withResolvers();
+      const zipfile = new import_yazl.ZipFile();
+      const writeStream = (0, import_node_fs.createWriteStream)(tmpArchivePath);
+      writeStream.on("close", () => {
+        resolve();
+      });
+      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
+      });
+      for await (const entry of this.list()) {
+        if (entry.relativePath === "mimetype") continue;
+        zipfile.addFile(entry.absolutePath, entry.relativePath, {
+          compress: !isAudioFile(entry.absolutePath)
+        });
+      }
+      zipfile.end();
+      await promise;
+      await (0, import_promises.cp)(tmpArchivePath, targetPath);
+    } catch (_) {
+      var _error = _, _hasError = true;
+    } finally {
+      var _promise = __callDispose(_stack, _error, _hasError);
+      _promise && await _promise;
+    }
+  }
+  dispose() {
+    (0, import_node_fs.rmSync)(this.rootPath, { recursive: true, force: true });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TmpFsAdapter
+});

package/dist/adapters/tmpfs.d.cts

@@ -0,0 +1,29 @@
+import { EpubStorageAdapter, EpubListEntry } from './interface.cjs';
+
+/**
+ * Extracts an EPUB archive to a temp directory and serves all I/O off
+ * the real filesystem.
+ * `Epub.using(TmpFsAdapter).from(...)` returns a writable {@link Epub}.
+ */
+declare class TmpFsAdapter implements EpubStorageAdapter {
+    readonly rootPath: string;
+    static readonly kind: "extracted-dir";
+    static readonly capabilities: {
+        readonly writable: true;
+    };
+    static init(source: string | Uint8Array): Promise<TmpFsAdapter>;
+    static initEmpty(): Promise<TmpFsAdapter>;
+    private constructor();
+    read(path: string): Promise<Uint8Array>;
+    read(path: string, encoding: "utf-8"): Promise<string>;
+    write(path: string, data: Uint8Array): Promise<void>;
+    write(path: string, data: string, encoding: "utf-8"): Promise<void>;
+    remove(path: string): Promise<void>;
+    archiveLength(path: string): Promise<number>;
+    list(): AsyncIterable<EpubListEntry>;
+    duplicate(): Promise<TmpFsAdapter>;
+    serialize(targetPath: string): Promise<void>;
+    dispose(): void;
+}
+
+export { TmpFsAdapter };