@storyteller-platform/epub 0.2.1 → 0.3.1

package/dist/index.js

@@ -1,45 +1,13 @@
-import {
-  ERR_DUPLICATED_NAME,
-  Uint8ArrayReader,
-  Uint8ArrayWriter,
-  ZipReader,
-  ZipWriter
-} from "@zip.js/zip.js";
+import { PortablePath, ppath } from "@yarnpkg/fslib";
+import { DEFAULT_COMPRESSION_LEVEL, ZipFS } from "@yarnpkg/libzip";
 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 { 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);
+  constructor(zipFs) {
+    this.zipFs = zipFs;
     this.readXhtmlItemContents = memoize(
       this.readXhtmlItemContents.bind(this),
       // This isn't unnecessary, the generic here just isn't handling the
@@ -194,21 +162,10 @@ ${JSON.stringify(element, null, 2)}`
   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.
@@ -226,7 +183,7 @@ ${JSON.stringify(element, null, 2)}`
     creators,
     contributors
   }, additionalMetadata = []) {
-    const entries = [];
+    const zipFs = new ZipFS();
     const encoder = new TextEncoder();
     const container = encoder.encode(`<?xml version="1.0"?>
 <container>
@@ -235,8 +192,10 @@ ${JSON.stringify(element, null, 2)}`
   </rootfiles>
 </container>
 `);
-    entries.push(
-      new EpubEntry({ filename: "META-INF/container.xml", data: container })
+    await zipFs.mkdirpPromise(ppath.join(PortablePath.root, "META-INF"));
+    await zipFs.writeFilePromise(
+      ppath.join(PortablePath.root, "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">
@@ -248,10 +207,12 @@ ${JSON.stringify(element, null, 2)}`
   </spine>
 </package>
 `);
-    entries.push(
-      new EpubEntry({ filename: "OEBPS/content.opf", data: packageDocument })
+    await zipFs.mkdirpPromise(ppath.join(PortablePath.root, "OEBPS"));
+    await zipFs.writeFilePromise(
+      ppath.join(PortablePath.root, "OEBPS", "content.opf"),
+      packageDocument
     );
-    const epub = new this(entries);
+    const epub = new this(zipFs);
     const metadata = [
       {
         id: "pub-id",
@@ -287,42 +248,30 @@ ${JSON.stringify(element, null, 2)}`
    *        path to an EPUB file on disk, or a Uint8Array representing
    *        the data of the EPUB publication.
    */
+  // eslint-disable-next-line @typescript-eslint/require-await
   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());
+    const epub = new this(
+      // TODO: Is this cast chill?
+      new ZipFS(pathOrData)
+    );
     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);
+    await this.zipFs.removePromise(filename);
   }
   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;
+    return await this.zipFs.readFilePromise(path, encoding);
   }
   async getRootfile() {
     var _a;
     if (this.rootfile !== null) return this.rootfile;
     const containerString = await this.getFileData(
-      "META-INF/container.xml",
+      ppath.join(PortablePath.root, "META-INF", "container.xml"),
       "utf-8"
     );
     if (!containerString)
@@ -349,11 +298,12 @@ ${JSON.stringify(element, null, 2)}`
         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"]))
+    const fullPath = (_a = rootfile == null ? void 0 : rootfile[":@"]) == null ? void 0 : _a["@_full-path"];
+    if (!fullPath)
       throw new Error(
         "Failed to parse EPUB container.xml: Found no rootfile element"
       );
-    this.rootfile = rootfile[":@"]["@_full-path"];
+    this.rootfile = ppath.resolve(PortablePath.root, fullPath);
     return this.rootfile;
   }
   migratePackageDocument(packageDocument) {
@@ -416,7 +366,7 @@ ${JSON.stringify(element, null, 2)}`
         produced ?? packageDocument
       );
       const rootfile = await this.getRootfile();
-      this.writeEntryContents(rootfile, updatedPackageDocument, "utf-8");
+      await this.writeEntryContents(rootfile, updatedPackageDocument, "utf-8");
     });
   }
   /**
@@ -555,6 +505,34 @@ ${JSON.stringify(element, null, 2)}`
     const metadata = metadataElement.metadata.map((node) => Epub.parseMetadataItem(node)).filter((node) => !!node);
     return metadata;
   }
+  /**
+   * Retrieve the identifier from the dc:identifier element
+   * in the EPUB metadata.
+   *
+   * If there is no dc:identifier element, returns null.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getIdentifier() {
+    const metadata = await this.getMetadata();
+    const entry = metadata.find(({ type }) => type === "dc:identifier");
+    return (entry == null ? void 0 : entry.value) ?? null;
+  }
+  /**
+   * Set the dc:identifier metadata element with the provided string.
+   *
+   * Updates the existing dc:identifier element if one exists.
+   * Otherwise creates a new element
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async setIdentifier(identifier) {
+    await this.replaceMetadata(({ type }) => type === "dc:identifier", {
+      type: "dc:identifier",
+      properties: {},
+      value: identifier
+    });
+  }
   /**
    * Even "EPUB 3" publications sometimes still only use the
    * EPUB 2 specification for identifying the cover image.
@@ -1448,9 +1426,8 @@ ${JSON.stringify(element, null, 2)}`
    * 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);
+    const startPath = ppath.dirname(from);
+    return ppath.resolve(PortablePath.root, startPath, href);
   }
   async readItemContents(id, encoding) {
     const rootfile = await this.getRootfile();
@@ -1495,11 +1472,9 @@ ${JSON.stringify(element, null, 2)}`
     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 writeEntryContents(path, contents, encoding) {
+    await this.zipFs.mkdirpPromise(ppath.dirname(path));
+    await this.zipFs.writeFilePromise(path, contents, encoding);
   }
   async writeItemContents(id, contents, encoding) {
     const rootfile = await this.getRootfile();
@@ -1510,9 +1485,9 @@ ${JSON.stringify(element, null, 2)}`
     memoize.clear(this.readXhtmlItemContents);
     const href = this.resolveHref(rootfile, manifestItem.href);
     if (encoding === "utf-8") {
-      this.writeEntryContents(href, contents, encoding);
+      await this.writeEntryContents(href, contents, encoding);
     } else {
-      this.writeEntryContents(href, contents);
+      await this.writeEntryContents(href, contents);
     }
   }
   /**
@@ -1575,7 +1550,9 @@ ${JSON.stringify(element, null, 2)}`
           ...item.mediaType && { "media-type": item.mediaType },
           ...item.fallback && { fallback: item.fallback },
           ...item.mediaOverlay && { "media-overlay": item.mediaOverlay },
-          ...item.properties && { properties: item.properties.join(" ") }
+          ...item.properties && {
+            properties: item.properties.join(" ")
+          }
         })
       );
     });
@@ -1587,7 +1564,8 @@ ${JSON.stringify(element, null, 2)}`
         contents
       )
     ) : contents;
-    this.entries.push(new EpubEntry({ filename, data }));
+    await this.zipFs.mkdirpPromise(ppath.dirname(filename));
+    await this.zipFs.writeFilePromise(filename, data);
   }
   /**
    * Update the manifest entry for an existing item.
@@ -1737,19 +1715,21 @@ ${JSON.stringify(element, null, 2)}`
       }
     });
   }
+  discardAndClose() {
+    this.zipFs.discardAndClose();
+    this.rootfile = null;
+    this.manifest = null;
+    this.spine = null;
+  }
   /**
    * 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() {
+  async getArrayAndClose() {
     await this.replaceMetadata(
       (entry) => entry.properties["property"] === "dcterms:modified",
       {
@@ -1759,48 +1739,19 @@ ${JSON.stringify(element, null, 2)}`
         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;
-        }
-      })
+    this.zipFs.level = 0;
+    await this.zipFs.writeFilePromise(
+      ppath.join(PortablePath.root, "mimetype"),
+      "application/epub+zip",
+      "utf-8"
     );
-    const data = await this.zipWriter.close();
-    this.dataWriter = new Uint8ArrayWriter();
-    this.zipWriter = new ZipWriter(this.dataWriter);
-    return data;
+    this.zipFs.level = DEFAULT_COMPRESSION_LEVEL;
+    return this.zipFs.getBufferAndClose();
+  }
+  [Symbol.dispose]() {
+    if (this.zipFs.ready) {
+      this.discardAndClose();
+    }
   }
 }
 export {

package/dist/node.cjs

@@ -23,14 +23,21 @@ __export(node_exports, {
 module.exports = __toCommonJS(node_exports);
 var import_promises = require("node:fs/promises");
 var import_node_path = require("node:path");
+var import_fslib = require("@yarnpkg/fslib");
+var import_libzip = require("@yarnpkg/libzip");
 var import_fs = require("@storyteller-platform/fs");
 var import_index = require("./index.cjs");
 class Epub extends import_index.Epub {
-  static create(...args) {
-    return super.create(...args);
+  static create(dc, additionalMetadata = []) {
+    return super.create(dc, additionalMetadata);
   }
   static async from(...args) {
     const pathOrData = args[0];
+    if (typeof pathOrData === "string") {
+      return new Epub(
+        new import_libzip.ZipFS(import_fslib.npath.toPortablePath(import_fslib.npath.resolve(pathOrData)))
+      );
+    }
     const fileData = typeof pathOrData === "string" ? await (0, import_fs.streamFile)(pathOrData) : pathOrData;
     return super.from(fileData);
   }
@@ -38,10 +45,6 @@ class Epub extends import_index.Epub {
    * Write the current contents of the Epub to a new
    * EPUB archive on disk.
    *
-   * 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.
@@ -50,13 +53,9 @@ class Epub extends import_index.Epub {
    *  parent directory does not need te exist -- the path will be
    *  recursively created.
    */
-  async writeToFile(path) {
-    const data = await this.writeToArray();
-    if (!data.length)
-      throw new Error(
-        "Failed to write zip archive to file; writer returned no data"
-      );
+  async saveAndClose(path) {
     await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
+    const data = await this.getArrayAndClose();
     await (0, import_promises.writeFile)(path, data);
   }
 }

package/dist/node.d.cts

@@ -1,19 +1,15 @@
-import { Epub as Epub$1 } from './index.cjs';
-export { AlternateScript, Collection, DcCreator, DcSubject, DublinCore, ElementName, EpubMetadata, ManifestItem, MetadataEntry, ParsedXml, XmlElement, XmlNode, XmlTextNode } from './index.cjs';
-import '@zip.js/zip.js';
+import { Epub as Epub$1, DublinCore, EpubMetadata } from './index.cjs';
+export { AlternateScript, Collection, DcCreator, DcSubject, ElementName, ManifestItem, MetadataEntry, ParsedXml, XmlElement, XmlNode, XmlTextNode } from './index.cjs';
+import '@yarnpkg/libzip';
 import 'fast-xml-parser';
 
 declare class Epub extends Epub$1 {
-    static create(...args: Parameters<typeof Epub$1.create>): Promise<Epub>;
+    static create(dc: DublinCore, additionalMetadata?: EpubMetadata): Promise<Epub>;
     static from(...args: Parameters<typeof Epub$1.from>): Promise<Epub>;
     /**
      * Write the current contents of the Epub to a new
      * EPUB archive on disk.
      *
-     * 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.
@@ -22,7 +18,7 @@ declare class Epub extends Epub$1 {
      *  parent directory does not need te exist -- the path will be
      *  recursively created.
      */
-    writeToFile(path: string): Promise<void>;
+    saveAndClose(path: string): Promise<void>;
 }
 
-export { Epub };
+export { DublinCore, Epub, EpubMetadata };

package/dist/node.d.ts

@@ -1,19 +1,15 @@
-import { Epub as Epub$1 } from './index.js';
-export { AlternateScript, Collection, DcCreator, DcSubject, DublinCore, ElementName, EpubMetadata, ManifestItem, MetadataEntry, ParsedXml, XmlElement, XmlNode, XmlTextNode } from './index.js';
-import '@zip.js/zip.js';
+import { Epub as Epub$1, DublinCore, EpubMetadata } from './index.js';
+export { AlternateScript, Collection, DcCreator, DcSubject, ElementName, ManifestItem, MetadataEntry, ParsedXml, XmlElement, XmlNode, XmlTextNode } from './index.js';
+import '@yarnpkg/libzip';
 import 'fast-xml-parser';
 
 declare class Epub extends Epub$1 {
-    static create(...args: Parameters<typeof Epub$1.create>): Promise<Epub>;
+    static create(dc: DublinCore, additionalMetadata?: EpubMetadata): Promise<Epub>;
     static from(...args: Parameters<typeof Epub$1.from>): Promise<Epub>;
     /**
      * Write the current contents of the Epub to a new
      * EPUB archive on disk.
      *
-     * 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.
@@ -22,7 +18,7 @@ declare class Epub extends Epub$1 {
      *  parent directory does not need te exist -- the path will be
      *  recursively created.
      */
-    writeToFile(path: string): Promise<void>;
+    saveAndClose(path: string): Promise<void>;
 }
 
-export { Epub };
+export { DublinCore, Epub, EpubMetadata };

package/dist/node.js

@@ -1,13 +1,22 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { npath } from "@yarnpkg/fslib";
+import { ZipFS } from "@yarnpkg/libzip";
 import { streamFile } from "@storyteller-platform/fs";
-import { Epub as BaseEpub } from "./index.js";
+import {
+  Epub as BaseEpub
+} from "./index.js";
 class Epub extends BaseEpub {
-  static create(...args) {
-    return super.create(...args);
+  static create(dc, additionalMetadata = []) {
+    return super.create(dc, additionalMetadata);
   }
   static async from(...args) {
     const pathOrData = args[0];
+    if (typeof pathOrData === "string") {
+      return new Epub(
+        new ZipFS(npath.toPortablePath(npath.resolve(pathOrData)))
+      );
+    }
     const fileData = typeof pathOrData === "string" ? await streamFile(pathOrData) : pathOrData;
     return super.from(fileData);
   }
@@ -15,10 +24,6 @@ class Epub extends BaseEpub {
    * Write the current contents of the Epub to a new
    * EPUB archive on disk.
    *
-   * 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.
@@ -27,13 +32,9 @@ class Epub extends BaseEpub {
    *  parent directory does not need te exist -- the path will be
    *  recursively created.
    */
-  async writeToFile(path) {
-    const data = await this.writeToArray();
-    if (!data.length)
-      throw new Error(
-        "Failed to write zip archive to file; writer returned no data"
-      );
+  async saveAndClose(path) {
     await mkdir(dirname(path), { recursive: true });
+    const data = await this.getArrayAndClose();
     await writeFile(path, data);
   }
 }

package/package.json

@@ -1,34 +1,20 @@
 {
   "name": "@storyteller-platform/epub",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",
   "exports": {
-    ".": {
-      "@storyteller": "./index.ts",
-      "@storyteller-node": "./node.ts",
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+    "import": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js",
+      "browser": "./dist/index.js"
     },
-    "./node": {
-      "@storyteller": "./node.ts",
-      "@storyteller-node": "./node.ts",
-      "import": {
-        "types": "./dist/node.d.ts",
-        "default": "./dist/node.js"
-      },
-      "require": {
-        "types": "./dist/node.d.cts",
-        "default": "./dist/node.cjs"
-      }
+    "require": {
+      "types": "./dist/node.d.cts",
+      "default": "./dist/node.cjs",
+      "browser": "./dist/index.cjs"
     }
   },
   "files": [
@@ -47,19 +33,21 @@
     "@storyteller-platform/tsup": "^0.1.0",
     "@tsconfig/strictest": "^2.0.5",
     "@types/mime-types": "^2",
-    "@types/node": "^22.10.1",
+    "@types/node": "^24.0.0",
     "markdown-toc": "^1.2.0",
     "remark-toc": "^9.0.0",
     "tsup": "^8.5.0",
     "tsx": "^4.19.2",
-    "typedoc": "^0.28.4",
+    "typedoc": "^0.28.13",
     "typedoc-plugin-markdown": "^4.6.3",
     "typedoc-plugin-remark": "^1.2.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.2"
   },
   "dependencies": {
-    "@storyteller-platform/fs": "^0.1.2",
-    "@storyteller-platform/path": "^0.1.0",
+    "@storyteller-platform/fs": "^0.1.3",
+    "@storyteller-platform/path": "^0.1.1",
+    "@yarnpkg/fslib": "^3.1.3",
+    "@yarnpkg/libzip": "^3.2.2",
     "@zip.js/zip.js": "^2.0.0",
     "async-mutex": "^0.5.0",
     "fast-xml-parser": "^4.0.0",
@@ -68,6 +56,18 @@
     "nanoid": "^5.1.5"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "import": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js",
+        "browser": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/node.d.cts",
+        "default": "./dist/node.cjs",
+        "browser": "./dist/index.cjs"
+      }
+    }
   }
 }