@storyteller-platform/epub 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-/** @jsxImportSource @storyteller-platform/epub */
 import type { Document, Element, Node } from "@xmldom/xmldom";
 import type { AdapterOptions, ArchiveSource, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageKind } from "./adapters/interface.ts";
 import * as Upgrade from "./upgrade.tsx";
@@ -24,6 +23,17 @@ declare global {
         }
     }
 }
+declare module "@esfx/async-readerwriterlock" {
+    interface AsyncReaderWriterLockReader {
+        [Symbol.dispose](): void;
+    }
+    interface AsyncReaderWriterLockWriter {
+        [Symbol.dispose](): void;
+    }
+    interface AsyncReaderWriterLockUpgradeableReader {
+        [Symbol.dispose](): void;
+    }
+}
 export type ManifestItem = {
     id: string;
     href: string;
@@ -177,7 +187,7 @@ export declare class Epub {
     private rootfile;
     private manifest;
     private spine;
-    private packageMutex;
+    private packageLock;
     /**
      * Storage backend kind in use for this instance
      *
@@ -246,14 +256,15 @@ export declare class Epub {
     getRootfile(): Promise<string>;
     getPackageDocumentSource(): Promise<string>;
     private getPackageDocument;
-    getPackageElement(): Promise<Element>;
+    getPackageElement(lock?: boolean): Promise<Element>;
     /**
      * Safely modify the package document, without race conditions.
      *
      * Since the reading the package document is an async process,
      * multiple simultaneously dispatched function calls that all
      * attempt to modify it can clobber each other's changes. This
-     * method uses a mutex to ensure that each update runs exclusively.
+     * method uses a read/write lock to ensure that each update runs
+     * exclusively.
      *
      * @param producer The function to update the package document. If
      *    it returns a new package document, that will be persisted, otherwise
@@ -264,7 +275,9 @@ export declare class Epub {
      * Retrieve the manifest for the Epub.
      *
      * This is represented as a map from each manifest items'
-     * id to the rest of its properties.
+     * id to the rest of its properties. Manifest hrefs are
+     * always URI-encoded (e.g. `chapter one.xhtml` -> `chapter%20one.xhtml`),
+     * even if the raw XML is (incorrectly) not URI-encoded.
      *
      * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
      */

package/dist/index.js

@@ -1,5 +1,58 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { jsx as _jsx, jsxs as _jsxs } from "@storyteller-platform/epub/jsx-runtime";
-import { Mutex } from "async-mutex";
+/** @jsxImportSource @storyteller-platform/epub */
+import { AsyncReaderWriterLock } from "@esfx/async-readerwriterlock";
 import memoize from "mem";
 import { MediaType } from "@storyteller-platform/media-types";
 import { copyFile } from "#files";
@@ -24,6 +77,16 @@ export class EpubReadOnlyError extends Error {
  * makes it easy to distinguish normal hrefs from external/invalid ones
  */
 const ENTRY_ORIGIN = "epub:///";
+function ensureEncodedPath(href) {
+    let decoded = href;
+    try {
+        decoded = decodeURIComponent(href);
+    }
+    catch {
+        // href may be un-encoded but contain a raw % symbol
+    }
+    return entryToUrlPath(decoded);
+}
 /**
  * Needs to be convoluted like this, bc
  * - `encodeURIComponent` escapes `/` and `\`
@@ -132,7 +195,7 @@ export class Epub {
     rootfile = null;
     manifest = null;
     spine = null;
-    packageMutex = new Mutex();
+    packageLock = new AsyncReaderWriterLock();
     /**
      * Storage backend kind in use for this instance
      *
@@ -263,15 +326,32 @@ export class Epub {
         ensureOpfNamespace(packageDocument);
         return packageDocument;
     }
-    async getPackageElement() {
-        const packageDocument = await this.getPackageDocument();
-        const packageElement = packageDocument.documentElement?.localName === "package"
-            ? packageDocument.documentElement
-            : null;
-        if (!packageElement) {
-            throw new Error("Failed to parse EPUB: Found no package element in package document");
+    async getPackageElement(lock = true) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const stack = __addDisposableResource(env_1, new DisposableStack(), false);
+            if (!lock) {
+                stack.adopt(await this.packageLock.read(), (lock) => {
+                    lock.unlock();
+                });
+            }
+            const packageDocument = await this.getPackageDocument();
+            stack.dispose();
+            const packageElement = packageDocument.documentElement?.localName === "package"
+                ? packageDocument.documentElement
+                : null;
+            if (!packageElement) {
+                throw new Error("Failed to parse EPUB: Found no package element in package document");
+            }
+            return packageElement;
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
         }
-        return packageElement;
     }
     /**
      * Safely modify the package document, without race conditions.
@@ -279,15 +359,18 @@ export class Epub {
      * Since the reading the package document is an async process,
      * multiple simultaneously dispatched function calls that all
      * attempt to modify it can clobber each other's changes. This
-     * method uses a mutex to ensure that each update runs exclusively.
+     * method uses a read/write lock to ensure that each update runs
+     * exclusively.
      *
      * @param producer The function to update the package document. If
      *    it returns a new package document, that will be persisted, otherwise
      *    it will be assumed that the package document was modified in place.
      */
     async withPackage(producer) {
-        this.assertWritable();
-        await this.packageMutex.runExclusive(async () => {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            this.assertWritable();
+            const _ = __addDisposableResource(env_2, await this.packageLock.write(), false);
             const packageDocument = await this.getPackageDocument();
             const packageElement = packageDocument.documentElement?.localName === "package"
                 ? packageDocument.documentElement
@@ -299,43 +382,65 @@ export class Epub {
             const updatedPackageDocument = serialize(produced ?? packageDocument);
             const rootfile = await this.getRootfile();
             await this.writeEntryContents(rootfile, updatedPackageDocument, "utf-8");
-        });
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
     }
     /**
      * Retrieve the manifest for the Epub.
      *
      * This is represented as a map from each manifest items'
-     * id to the rest of its properties.
+     * id to the rest of its properties. Manifest hrefs are
+     * always URI-encoded (e.g. `chapter one.xhtml` -> `chapter%20one.xhtml`),
+     * even if the raw XML is (incorrectly) not URI-encoded.
      *
      * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
      */
     async getManifest() {
-        if (this.manifest !== null)
-            return this.manifest;
-        const packageElement = await this.getPackageElement();
-        const manifest = findXmlChildByNameNS(NS.opf, "manifest", packageElement);
-        if (!manifest) {
-            throw new Error("Failed to parse EPUB: Found no manifest element in package document");
-        }
-        this.manifest = Array.from(manifest.children).reduce((acc, item) => {
-            const id = item.getAttribute("id");
-            const href = item.getAttribute("href");
-            if (!id || !href) {
-                return acc;
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (this.manifest !== null)
+                return this.manifest;
+            const _ = __addDisposableResource(env_3, await this.packageLock.read(), false);
+            const packageElement = await this.getPackageElement(false);
+            const manifest = findXmlChildByNameNS(NS.opf, "manifest", packageElement);
+            if (!manifest) {
+                throw new Error("Failed to parse EPUB: Found no manifest element in package document");
             }
-            return {
-                ...acc,
-                [id]: {
+            const manifestRecord = {};
+            for (const item of Array.from(manifest.children)) {
+                const id = item.getAttribute("id");
+                const hrefAttr = item.getAttribute("href");
+                if (!hrefAttr)
+                    continue;
+                const href = ensureEncodedPath(hrefAttr);
+                if (!id || !href) {
+                    continue;
+                }
+                manifestRecord[id] = {
                     id,
                     href,
                     mediaType: item.getAttribute("media-type") ?? undefined,
                     mediaOverlay: item.getAttribute("media-overlay") ?? undefined,
                     fallback: item.getAttribute("fallback") ?? undefined,
                     properties: item.getAttribute("properties")?.split(" ") ?? undefined,
-                },
-            };
-        }, {});
-        return this.manifest;
+                };
+            }
+            this.manifest = manifestRecord;
+            return this.manifest;
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            __disposeResources(env_3);
+        }
     }
     /**
      * Returns the first index in the metadata element's children array
@@ -477,12 +582,12 @@ export class Epub {
      * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
      */
     async setUniqueIdentifier(identifier) {
-        await this.withPackage(async (packageElement) => {
+        await this.withPackage((packageElement) => {
             const metadata = findXmlChildByNameNS(NS.opf, "metadata", packageElement);
             if (!metadata) {
                 throw new Error("Failed to parse EPUB: found no metadata element in package document");
             }
-            let uniqueId = await this.getUniqueIdentifierId();
+            let uniqueId = packageElement.getAttribute("unique-identifier") ?? null;
             if (!uniqueId) {
                 // Create a new unique identifier id
                 const newUniqueId = xmlId();
@@ -1187,8 +1292,12 @@ export class Epub {
      * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
      */
     async setPackageVocabularyPrefix(prefix, uri) {
-        await this.withPackage(async (packageElement) => {
-            const prefixes = await this.getPackageVocabularyPrefixes();
+        await this.withPackage((packageElement) => {
+            const prefixValue = packageElement.getAttribute("prefix");
+            const matches = prefixValue?.matchAll(/(?:([a-z]+): +(\S+)\s*)/gs);
+            const prefixes = matches
+                ? Array.from(matches).reduce((acc, match) => match[1] && match[2] ? { ...acc, [match[1]]: match[2] } : acc, {})
+                : {};
             prefixes[prefix] = uri;
             packageElement.setAttribute("prefix", Object.entries(prefixes)
                 .map(([p, u]) => `${p}: ${u}`)
@@ -1538,21 +1647,32 @@ export class Epub {
         return this.addCreator(contributor, index, "contributor");
     }
     async getSpine() {
-        if (this.spine !== null)
+        const env_4 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (this.spine !== null)
+                return this.spine;
+            const _ = __addDisposableResource(env_4, await this.packageLock.read(), false);
+            const packageElement = await this.getPackageElement(false);
+            const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
+            if (!spine)
+                throw new Error("Failed to parse EPUB: Found no spine element in package document");
+            this.spine = Array.from(spine.children)
+                .map((itemref) => {
+                return {
+                    itemRef: itemref.getAttribute("idref"),
+                    linear: itemref.getAttribute("linear") !== "no",
+                };
+            })
+                .filter((itemref) => !!itemref.itemRef);
             return this.spine;
-        const packageElement = await this.getPackageElement();
-        const spine = findXmlChildByNameNS(NS.opf, "spine", packageElement);
-        if (!spine)
-            throw new Error("Failed to parse EPUB: Found no spine element in package document");
-        this.spine = Array.from(spine.children)
-            .map((itemref) => {
-            return {
-                itemRef: itemref.getAttribute("idref"),
-                linear: itemref.getAttribute("linear") !== "no",
-            };
-        })
-            .filter((itemref) => !!itemref.itemRef);
-        return this.spine;
+        }
+        catch (e_4) {
+            env_4.error = e_4;
+            env_4.hasError = true;
+        }
+        finally {
+            __disposeResources(env_4);
+        }
     }
     /**
      * Retrieve the manifest items that make up the Epub's spine.
@@ -1605,9 +1725,9 @@ export class Epub {
             insert(spine, item, index === undefined
                 ? null
                 : (Array.from(spine.children)[index] ?? null));
+            // Reset the spine cache
+            this.spine = null;
         });
-        // Reset the spine cache
-        this.spine = null;
     }
     /**
      * Remove the spine item at the specified index.
@@ -1622,9 +1742,9 @@ export class Epub {
             const itemref = Array.from(spine.children)[index];
             if (itemref)
                 spine.removeChild(itemref);
+            // Reset the spine cache
+            this.spine = null;
         });
-        // Reset the spine cache
-        this.spine = null;
     }
     async getNavigationChildren(ol, navHref, { resolveToRoot } = {}) {
         const children = [];
@@ -1781,8 +1901,6 @@ export class Epub {
          Use if resolving a relative href from a file other than the package document.
      */
     async resolveHref(href, relativeTo, { toRoot } = {}) {
-        if (href.startsWith("#"))
-            return href;
         const rootfile = await this.getRootfile();
         const from = relativeTo
             ? await this.resolveEntry(rootfile, relativeTo)
@@ -1790,7 +1908,7 @@ export class Epub {
         const url = resolveEntryUrl(from, href);
         if (!url)
             return href;
-        const entry = (await this.entryForUrl(url)).split("/");
+        const entry = url.pathname.slice(1).split("/");
         const base = toRoot ? [] : rootfile.split("/").slice(0, -1);
         let shared = 0;
         while (shared < base.length && base[shared] === entry[shared]) {
@@ -1798,9 +1916,9 @@ export class Epub {
         }
         const relative = [
             ...Array(base.length - shared).fill(".."),
-            ...entry.slice(shared).map(encodeURIComponent),
+            ...entry.slice(shared),
         ];
-        return relative.join("/") + url.hash;
+        return ensureEncodedPath(relative.join("/")) + url.hash;
     }
     async readFileContents(href, relativeTo, encoding) {
         const rootfile = await this.getRootfile();
@@ -1946,17 +2064,20 @@ export class Epub {
             if (!href)
                 return;
             await this.removeEntry(href);
+            // Reset the cached manifest and spine, so that they will be read from
+            // the updated XML next time
+            this.manifest = null;
+            this.spine = null;
         });
-        // Reset the cached manifest and spine, so that they will be read from
-        // the updated XML next time
-        this.manifest = null;
-        this.spine = null;
     }
     async addManifestItem(item, contents, encoding) {
         const existingItems = Object.values(await this.getManifest());
         if (existingItems.some((existing) => existing.id === item.id)) {
             throw new Error(`Cannot add manifest item: an item with the id "${item.id}" already exists`);
         }
+        if (item.href !== ensureEncodedPath(item.href)) {
+            throw new Error(`Manifest hrefs must be URI encoded. Received ${item.href}`);
+        }
         // 4.2.1: hrefs that normalize and case-fold to the same path would
         // overwrite each other on a normalizing filesystem.
         const foldedHref = foldPathName(item.href);
@@ -1970,10 +2091,10 @@ export class Epub {
             if (!manifest)
                 throw new Error("Failed to parse EPUB: Found no manifest element in package document");
             insert(manifest, _jsx("item", { id: item.id, href: item.href, ...(item.mediaType && { "media-type": item.mediaType }), ...(item.fallback && { fallback: item.fallback }), ...(item.mediaOverlay && { "media-overlay": item.mediaOverlay }), ...(item.properties && { properties: item.properties.join(" ") }) }));
+            // Reset the cached manifest, so that it will be read from
+            // the updated XML next time
+            this.manifest = null;
         });
-        // Reset the cached manifest, so that it will be read from
-        // the updated XML next time
-        this.manifest = null;
         const rootfile = await this.getRootfile();
         const filename = await this.resolveEntry(rootfile, item.href);
         /* oxlint-disable typescript/no-unnecessary-type-assertion -- tsgolint treats these casts as unnecessary, but each one still narrows the value that is written out */
@@ -2006,10 +2127,10 @@ export class Epub {
                 }), ...(newItem.properties && {
                     properties: newItem.properties.join(" "),
                 }) }), existing);
+            // Reset the cached manifest, so that it will be read from
+            // the updated XML next time
+            this.manifest = null;
         });
-        // Reset the cached manifest, so that it will be read from
-        // the updated XML next time
-        this.manifest = null;
     }
     /**
      * Add a new metadata entry to the Epub.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storyteller-platform/epub",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "types": "dist/index.d.ts",
   "license": "MIT",
@@ -80,12 +80,12 @@
     "vitest": "^5.0.0"
   },
   "dependencies": {
+    "@esfx/async-readerwriterlock": "^1.0.0",
     "@storyteller-platform/fs": "^0.3.0",
     "@storyteller-platform/media-types": "^0.2.1",
     "@storyteller-platform/path": "^0.3.1",
     "@xmldom/xmldom": "^0.9.12",
     "@zip.js/zip.js": "^2.18.2",
-    "async-mutex": "^0.5.0",
     "mem": "^8.0.0",
     "nanoid": "^5.1.5",
     "yauzl-promise": "^4.0.0",