@storyteller-platform/epub 0.7.0 → 0.8.0

package/dist/zip.d.ts

@@ -0,0 +1,2 @@
+import { type ZipFile } from "yauzl-promise";
+export declare function openZip(source: string | Uint8Array): Promise<ZipFile>;

package/dist/zip.js

@@ -0,0 +1,137 @@
+import { createReadStream } from "node:fs";
+import { open as openFile } from "node:fs/promises";
+import { Reader, fromBuffer, fromReader, open, } from "yauzl-promise";
+const EOCDR_SIGNATURE = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const EOCDR_SIZE = 22;
+const MAX_TAIL_SCAN = 1024 * 1024;
+function toBuffer(source) {
+    return Buffer.isBuffer(source)
+        ? source
+        : Buffer.from(source.buffer, source.byteOffset, source.byteLength);
+}
+function findArchiveEnd(tail, tailStart, fileSize) {
+    let searchFrom = tail.length - EOCDR_SIZE;
+    while (searchFrom >= 0) {
+        const index = tail.lastIndexOf(EOCDR_SIGNATURE, searchFrom);
+        if (index === -1)
+            return null;
+        const commentLength = tail.readUInt16LE(index + 20);
+        const end = tailStart + index + EOCDR_SIZE + commentLength;
+        if (end < fileSize)
+            return end;
+        searchFrom = index - 1;
+    }
+    return null;
+}
+async function readExactly(handle, length, position) {
+    const buffer = Buffer.allocUnsafe(length);
+    let offset = 0;
+    while (offset < length) {
+        const { bytesRead } = await handle.read(buffer, offset, length - offset, position + offset);
+        if (bytesRead === 0)
+            return null;
+        offset += bytesRead;
+    }
+    return buffer;
+}
+async function findFileArchiveEnd(path) {
+    let handle;
+    try {
+        handle = await openFile(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const { size } = await handle.stat();
+        const tailLength = Math.min(size, MAX_TAIL_SCAN);
+        if (tailLength < EOCDR_SIZE)
+            return null;
+        const tailStart = size - tailLength;
+        const tail = await readExactly(handle, tailLength, tailStart);
+        if (!tail)
+            return null;
+        return findArchiveEnd(tail, tailStart, size);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Basically sometimes EPUB 2s have some garbage at the end of the file after
+ * the End of Central Directory Record, which leads to
+ * `yauzl` throwing an "End of Central Directory Record not found" error
+ *
+ * This is an attempt to, when that error happens, try to read the file from the end and find the End of Central Directory Record, then clean up the garbage at the end of the file.
+ */
+class TruncatedFileReader extends Reader {
+    path;
+    handle = null;
+    constructor(path) {
+        super();
+        this.path = path;
+    }
+    async _open() {
+        this.handle = await openFile(this.path, "r");
+        return {};
+    }
+    async _close() {
+        const handle = this.handle;
+        this.handle = null;
+        if (handle)
+            await handle.close();
+        return {};
+    }
+    async _read(start, length) {
+        if (!this.handle)
+            throw new Error(`reader for ${this.path} is not open`);
+        const buffer = await readExactly(this.handle, length, start);
+        if (!buffer) {
+            throw new Error(`unexpected end of file reading ${this.path}`);
+        }
+        return buffer;
+    }
+    _createReadStream(start, length) {
+        return createReadStream(this.path, { start, end: start + length - 1 });
+    }
+}
+async function openBufferZip(data) {
+    try {
+        return await fromBuffer(data);
+    }
+    catch (error) {
+        const tailStart = Math.max(0, data.length - MAX_TAIL_SCAN);
+        const end = findArchiveEnd(data.subarray(tailStart), tailStart, data.length);
+        if (end === null)
+            throw error;
+        try {
+            return await fromBuffer(data.subarray(0, end));
+        }
+        catch {
+            throw error;
+        }
+    }
+}
+async function openFileZip(path) {
+    try {
+        return await open(path);
+    }
+    catch (error) {
+        const end = await findFileArchiveEnd(path);
+        if (end === null)
+            throw error;
+        const reader = new TruncatedFileReader(path);
+        try {
+            return await fromReader(reader, end);
+        }
+        catch {
+            await reader._close().catch(() => undefined);
+            throw error;
+        }
+    }
+}
+export async function openZip(source) {
+    return typeof source === "string"
+        ? openFileZip(source)
+        : openBufferZip(toBuffer(source));
+}

package/package.json

@@ -1,60 +1,52 @@
 {
   "name": "@storyteller-platform/epub",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
-  "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "license": "MIT",
   "exports": {
-    "import": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "require": {
-      "types": "./dist/index.d.cts",
-      "default": "./dist/index.cjs"
-    }
+    "types": "./dist/index.d.ts",
+    "default": "./dist/index.js"
   },
   "files": [
     "dist/"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "rm -rf dist .tsbuild && tsc -b tsconfig.build.json",
     "readme:toc": "markdown-toc --maxdepth=5 --append='\n- [API Docs](#api-docs)' --bullets='-' -i readme-stub.md",
     "readme:api": "typedoc",
     "readme": "yarn readme:api && yarn readme:toc && cat readme-stub.md > README.md && tail -n +2 gen/README.md >> README.md",
     "install-epubcheck": "tsx scripts/install-epubcheck.ts",
-    "test": "yarn install-epubcheck && tsx -C @storyteller --test *.test.ts",
-    "test:watch": "yarn install-epubcheck && tsx -C @storyteller --test --watch *.test.ts",
+    "test": "yarn install-epubcheck && vitest run",
+    "test:watch": "yarn install-epubcheck && vitest",
     "prepack": "yarn build"
   },
   "devDependencies": {
-    "@storyteller-platform/eslint": "0.1.0",
-    "@storyteller-platform/tsup": "^0.1.0",
     "@tsconfig/strictest": "^2.0.5",
-    "@types/mime-types": "^2",
     "@types/node": "^24.0.0",
     "@types/yauzl-promise": "^4",
     "@types/yazl": "^3",
-    "eslint": "^8.0.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "markdown-toc": "^1.2.0",
     "remark-toc": "^9.0.0",
-    "tsup": "^8.5.0",
     "tsx": "^4.19.2",
-    "typedoc": "^0.28.13",
+    "typedoc": "^0.28.20",
     "typedoc-plugin-markdown": "^4.6.3",
     "typedoc-plugin-remark": "^1.2.0",
-    "typescript": "^5.9.2"
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^5.0.0"
   },
   "dependencies": {
     "@readium/shared": "^2.2.0",
-    "@storyteller-platform/fs": "^0.1.4",
-    "@storyteller-platform/path": "^0.1.3",
+    "@storyteller-platform/fs": "^0.3.0",
+    "@storyteller-platform/media-types": "^0.2.0",
+    "@storyteller-platform/path": "^0.3.0",
     "@zip.js/zip.js": "^2.0.0",
     "async-mutex": "^0.5.0",
-    "fast-xml-parser": "^4.0.1",
+    "fast-xml-builder": "^1.3.1",
+    "fast-xml-parser": "^5.11.1",
     "mem": "^8.0.0",
-    "mime-types": "^3.0.1",
     "nanoid": "^5.1.5",
     "yauzl-promise": "^4.0.0",
     "yazl": "^3.3.1"
@@ -62,14 +54,8 @@
   "publishConfig": {
     "access": "public",
     "exports": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   }
 }

package/dist/adapters/interface.cjs

@@ -1,16 +0,0 @@
-"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

@@ -1,69 +0,0 @@
-/**
- * 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

@@ -1,103 +0,0 @@
-"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

@@ -1,37 +0,0 @@
-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 };