@storyteller-platform/epub 0.7.1 → 0.8.0

package/dist/zip.d.ts

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

package/dist/zip.js

@@ -1,124 +1,137 @@
-import "./chunk-BIEQXUOY.js";
 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([80, 75, 5, 6]);
+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);
+    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;
+    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;
+    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();
-  }
+    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 {
-  constructor(path) {
-    super();
-    this.path = path;
-  }
-  handle = null;
-  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}`);
+    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 });
     }
-    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;
+        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(() => void 0);
-      throw error;
+        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;
+        }
     }
-  }
 }
-async function openZip(source) {
-  return typeof source === "string" ? openFileZip(source) : openBufferZip(toBuffer(source));
+export async function openZip(source) {
+    return typeof source === "string"
+        ? openFileZip(source)
+        : openBufferZip(toBuffer(source));
 }
-export {
-  openZip
-};

package/package.json

@@ -1,58 +1,51 @@
 {
   "name": "@storyteller-platform/epub",
-  "version": "0.7.1",
+  "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/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.2.0",
-    "@storyteller-platform/media-types": "^0.1.0",
-    "@storyteller-platform/path": "^0.2.0",
+    "@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",
     "nanoid": "^5.1.5",
     "yauzl-promise": "^4.0.0",
@@ -61,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,75 +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 {
-    /** location the adapter can read the entry back from, in whatever form it stores */
-    absolutePath: string;
-    /** the entry name, as it appears in the archive */
-    relativePath: string;
-}
-/**
- * Adapters only receive entry names, which is:
- * - the name a file has in the archive itself
- * - relative to the container root, slash-separated,
- * - already percent-decoded (eg `OEBPS/a b.xhtml`, not `OEBPS/a%20b.xhtml`)
- *
- * Adapter decides where to store files under what name
- * In previous versions of the EPUB lib, this was a little bit more muddled, leading to
- * eg the TmpFsAdapter trying to read `OEBPS/a%20b.xhtml`, whereas it was stored as `OEBPS/a b.xhtml`
- */
-interface EpubStorageAdapter {
-    read(entry: string): Promise<Uint8Array>;
-    read(entry: string, encoding: "utf-8"): Promise<string>;
-    /**
-     * Whether the archive holds an entry under exactly this name.
-     * Used to choose between different canditates for an href
-     * so should be exact
-     */
-    exists(entry: string): Promise<boolean>;
-    /**
-     * Length of an entry in bytes, for the readium page-count heuristic
-     * which expects compressed size when available
-     */
-    archiveLength(entry: string): Promise<number>;
-    /** Required for any mutation method on Epub */
-    write?(entry: string, data: Uint8Array): Promise<void>;
-    write?(entry: string, data: string, encoding: "utf-8"): Promise<void>;
-    /** Required for removeManifestItem / setCoverImage replacement */
-    remove?(entry: 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.
-     * Will throw if the archive is not a valid EPUB 3
-     */
-    init(source: string | Uint8Array, opts?: Opts): Promise<EpubStorageAdapter>;
-    /**
-     * Initialize an empty extract root for {@link Epub.create}.
-     * Only necessary for adapters that can write
-     */
-    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,93 +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_zip = require("../zip.cjs");
-class MemoryAdapter {
-  constructor(zip, entries, cache) {
-    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 = await (0, import_zip.openZip)(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;
-    }
-    return new MemoryAdapter(zip, entries, cache ? /* @__PURE__ */ new Map() : null);
-  }
-  async read(entry, encoding) {
-    var _a, _b;
-    const cached = (_a = this.cache) == null ? void 0 : _a.get(entry);
-    if (cached) {
-      return encoding ? cached.toString(encoding) : new Uint8Array(cached);
-    }
-    const zipEntry = this.entries.get(entry);
-    if (!zipEntry) {
-      const err = new Error(
-        `ENOENT: zip entry not found in EPUB archive: ${entry}`
-      );
-      err.code = "ENOENT";
-      throw err;
-    }
-    const stream = await zipEntry.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(entry, buf);
-    return encoding ? buf.toString(encoding) : new Uint8Array(buf);
-  }
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async exists(entry) {
-    return this.entries.has(entry);
-  }
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async archiveLength(entry) {
-    const zipEntry = this.entries.get(entry);
-    if (!zipEntry) return 0;
-    return zipEntry.compressedSize || zipEntry.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,36 +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 {
-    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();
-    read(entry: string): Promise<Uint8Array>;
-    read(entry: string, encoding: "utf-8"): Promise<string>;
-    exists(entry: string): Promise<boolean>;
-    archiveLength(entry: string): Promise<number>;
-    dispose(): void;
-}
-
-export { MemoryAdapter, type MemoryAdapterOptions };