@storyteller-platform/epub 0.7.0 → 0.8.0

package/dist/adapters/interface.d.ts

@@ -7,36 +7,46 @@
  *  - {@link MemoryAdapter} keeps an in-memory zip handle and supports
  *    reads only
  */
-type EpubStorageKind = "tmp-dir" | "in-memory" | (string & {});
-interface EpubStorageCapabilities {
+export type EpubStorageKind = "tmp-dir" | "in-memory" | (string & {});
+export interface EpubStorageCapabilities {
     /** when false, the Epub class refuses every mutation method at runtime */
     readonly writable: boolean;
 }
-interface EpubListEntry {
-    /** absolute path under {@link EpubStorageAdapter.rootPath} */
+export interface EpubListEntry {
+    /** location the adapter can read the entry back from, in whatever form it stores */
     absolutePath: string;
-    /** path relative to {@link EpubStorageAdapter.rootPath}, slash-separated */
+    /** the entry name, as it appears in the archive */
     relativePath: string;
 }
-interface EpubStorageAdapter {
+/**
+ * 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`
+ */
+export interface EpubStorageAdapter {
+    read(entry: string): Promise<Uint8Array>;
+    read(entry: string, encoding: "utf-8"): Promise<string>;
     /**
-     * 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
+     * Whether the archive holds an entry under exactly this name.
+     * Used to choose between different canditates for an href
+     * so should be exact
      */
-    readonly rootPath: string;
-    read(path: string): Promise<Uint8Array>;
-    read(path: string, encoding: "utf-8"): Promise<string>;
+    exists(entry: string): Promise<boolean>;
     /**
      * Length of an entry in bytes, for the readium page-count heuristic
      * which expects compressed size when available
      */
-    archiveLength(path: string): Promise<number>;
+    archiveLength(entry: 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>;
+    write?(entry: string, data: Uint8Array): Promise<void>;
+    write?(entry: string, data: string, encoding: "utf-8"): Promise<void>;
     /** Required for removeManifestItem / setCoverImage replacement */
-    remove?(path: string): Promise<void>;
+    remove?(entry: string): Promise<void>;
     /** Required for Epub.saveAndClose to walk the contents */
     list?(): AsyncIterable<EpubListEntry>;
     /** Required for Epub.copy */
@@ -46,24 +56,18 @@ interface EpubStorageAdapter {
     /** Always called on close or error */
     dispose(): void | Promise<void>;
 }
-interface EpubStorageAdapterClass<Opts extends object = object> {
+export 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.
+     * 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}.
-     *
-     * 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.
+     * 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 };
+export type AdapterOptions<A> = A extends EpubStorageAdapterClass<infer Opts> ? Opts : object;

package/dist/adapters/interface.js

@@ -0,0 +1 @@
+export {};

package/dist/adapters/memory.d.ts

@@ -1,6 +1,5 @@
-import { EpubStorageAdapter } from './interface.js';
-
-interface MemoryAdapterOptions {
+import type { EpubStorageAdapter } from "./interface.ts";
+export interface MemoryAdapterOptions {
     /**
      * per-entry decompressed buffer cache
      * turn it off when opening many EPUBs and reading each entry at most once
@@ -16,8 +15,7 @@ interface MemoryAdapterOptions {
  * read only
  *
  */
-declare class MemoryAdapter implements EpubStorageAdapter {
-    readonly rootPath: string;
+export declare class MemoryAdapter implements EpubStorageAdapter {
     private zip;
     private entries;
     private cache;
@@ -27,11 +25,9 @@ declare class MemoryAdapter implements EpubStorageAdapter {
     };
     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>;
+    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 };

package/dist/adapters/memory.js

@@ -1,83 +1,75 @@
-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;
+import { openZip } from "../zip.js";
+/**
+ * Loads an EPUB archive into memory and serves all I/O off the in-memory zip handle.
+ *
+ * read only
+ *
+ */
+export class MemoryAdapter {
+    zip;
+    entries;
+    cache;
+    static kind = "in-memory";
+    static capabilities = { writable: false };
+    static async init(source, opts = {}) {
+        const { cache = true, signal } = opts;
+        signal?.throwIfAborted();
+        const zip = await openZip(source);
+        const entries = new Map();
+        try {
+            for await (const entry of zip) {
+                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 ? new Map() : null);
     }
-    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);
+    constructor(zip, entries, cache) {
+        this.zip = zip;
+        this.entries = entries;
+        this.cache = cache;
     }
-    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;
+    async read(entry, encoding) {
+        const cached = this.cache?.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);
+        this.cache?.set(entry, buf);
+        return encoding ? buf.toString(encoding) : new Uint8Array(buf);
     }
-    const stream = await entry.openReadStream();
-    const chunks = [];
-    for await (const chunk of stream) {
-      chunks.push(chunk);
+    // 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() {
+        this.entries.clear();
+        this.cache?.clear();
+        // fire-and-forget: closing the handle just releases the fd
+        this.zip.close().catch(() => undefined);
     }
-    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.d.ts

@@ -1,12 +1,11 @@
-import { EpubStorageAdapter, EpubListEntry } from './interface.js';
-
+import type { EpubListEntry, EpubStorageAdapter } from "./interface.ts";
 /**
  * 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;
+export declare class TmpFsAdapter implements EpubStorageAdapter {
+    private readonly rootPath;
     static readonly kind: "extracted-dir";
     static readonly capabilities: {
         readonly writable: true;
@@ -14,16 +13,16 @@ declare class TmpFsAdapter implements EpubStorageAdapter {
     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>;
+    private diskPath;
+    read(entry: string): Promise<Uint8Array>;
+    read(entry: string, encoding: "utf-8"): Promise<string>;
+    write(entry: string, data: Uint8Array): Promise<void>;
+    write(entry: string, data: string, encoding: "utf-8"): Promise<void>;
+    remove(entry: string): Promise<void>;
+    exists(entry: string): Promise<boolean>;
+    archiveLength(entry: string): Promise<number>;
     list(): AsyncIterable<EpubListEntry>;
     duplicate(): Promise<TmpFsAdapter>;
     serialize(targetPath: string): Promise<void>;
     dispose(): void;
 }
-
-export { TmpFsAdapter };