@storyteller-platform/epub 0.6.3 → 0.7.0

package/dist/adapters/tmpfs.cjs

@@ -97,7 +97,8 @@ const AUDIO_FILE_EXTENSIONS = [
   ...WEBM_FILE_EXTENSIONS
 ];
 function isAudioFile(filenameOrExt) {
-  return AUDIO_FILE_EXTENSIONS.some((ext) => filenameOrExt.endsWith(ext));
+  const lowered = filenameOrExt.toLowerCase();
+  return AUDIO_FILE_EXTENSIONS.some((ext) => lowered.endsWith(ext));
 }
 function mintRootPath() {
   return (0, import_path.join)((0, import_node_os.tmpdir)(), `storyteller-platform-epub-${(0, import_node_crypto.randomUUID)()}`);

package/dist/adapters/tmpfs.js

@@ -41,7 +41,8 @@ const AUDIO_FILE_EXTENSIONS = [
   ...WEBM_FILE_EXTENSIONS
 ];
 function isAudioFile(filenameOrExt) {
-  return AUDIO_FILE_EXTENSIONS.some((ext) => filenameOrExt.endsWith(ext));
+  const lowered = filenameOrExt.toLowerCase();
+  return AUDIO_FILE_EXTENSIONS.some((ext) => lowered.endsWith(ext));
 }
 function mintRootPath() {
   return join(tmpdir(), `storyteller-platform-epub-${randomUUID()}`);

package/dist/index.cjs

@@ -582,12 +582,15 @@ ${JSON.stringify(element, null, 2)}`
     return metadata;
   }
   /**
-   * Retrieve the identifier from the dc:identifier element
+   * Retrieve the first 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
+   *
+   * @deprecated Use {@link getUniqueIdentifier} instead to get the unique identifier,
+   * or {@link getIdentifiers} to get all identifiers.
    */
   async getIdentifier() {
     const metadata = await this.getMetadata();
@@ -601,6 +604,8 @@ ${JSON.stringify(element, null, 2)}`
    * Otherwise creates a new element
    *
    * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   *
+   * @deprecated Use {@link setUniqueIdentifier} instead.
    */
   async setIdentifier(identifier) {
     await this.replaceMetadata(({ type }) => type === "dc:identifier", {
@@ -609,6 +614,395 @@ ${JSON.stringify(element, null, 2)}`
       value: identifier
     });
   }
+  /**
+   * Retrieve the identifier with the unique identifier id
+   * in the EPUB metadata.
+   *
+   * If there is no unique identifier id, returns the first dc:identifier element.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getUniqueIdentifier() {
+    const metadata = await this.getMetadata();
+    const uniqueId = await this.getUniqueIdentifierId();
+    if (!uniqueId) {
+      return null;
+    }
+    const entry = metadata.find(
+      ({ type, id }) => type === "dc:identifier" && id === uniqueId
+    );
+    return (entry == null ? void 0 : entry.value) ?? null;
+  }
+  /**
+   * Set the unique identifier id for the EPUB.
+   *
+   * Updates the existing dc:identifier element referenced by the unique identifier id if one exists.
+   * Otherwise creates a new element with the provided identifier, and sets the unique identifier id to the new element's id.
+   *
+   * Note: you likely shouldn't change the unique identifier id unless you are producing a new EPUB.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async setUniqueIdentifier(identifier) {
+    await this.withPackage(async (packageElement) => {
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata) {
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      }
+      let uniqueId = await this.getUniqueIdentifierId();
+      if (!uniqueId) {
+        const newUniqueId = (0, import_nanoid.nanoid)();
+        packageElement[":@"] = {
+          ...packageElement[":@"],
+          "@_unique-identifier": newUniqueId
+        };
+        uniqueId = newUniqueId;
+      }
+      const children = Epub.getXmlChildren(metadata);
+      const entry = Epub.findXmlChildByName(
+        "dc:identifier",
+        children,
+        (node) => {
+          var _a;
+          return ((_a = node[":@"]) == null ? void 0 : _a["@_id"]) === uniqueId;
+        }
+      );
+      if (entry) {
+        children.splice(
+          children.indexOf(entry),
+          1,
+          Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
+            Epub.createXmlTextNode(identifier)
+          ])
+        );
+        return;
+      }
+      children.push(
+        Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
+          Epub.createXmlTextNode(identifier)
+        ])
+      );
+    });
+  }
+  /**
+   * Retrieve the id of the publication's unique identifier, as declared by the
+   * package element's `unique-identifier` attribute.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getUniqueIdentifierId() {
+    var _a;
+    const packageElement = await this.getPackageElement();
+    return ((_a = packageElement[":@"]) == null ? void 0 : _a["@_unique-identifier"]) ?? null;
+  }
+  /**
+   * Collect `dc:identifier` or `dc:source` entries, attaching the value and
+   * scheme of any refining `identifier-type` meta (spec D.3.8) and a legacy
+   * `opf:scheme` attribute. Values are not interpreted.
+   *
+   * `onRefinement` is invoked for every other meta refining a collected entry,
+   * so callers can surface element-specific refinements (e.g. `source-of` on a
+   * `dc:source`).
+   */
+  static collectDcEntries(metadata, type, onRefinement) {
+    const entries = metadata.filter((entry) => entry.type === type && entry.value !== void 0).map((entry) => ({
+      // filtered above, so value is defined
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      value: entry.value,
+      ...entry.id && { id: entry.id },
+      ...entry.properties["opf:scheme"] && {
+        scheme: entry.properties["opf:scheme"]
+      }
+    }));
+    for (const meta of metadata) {
+      if (meta.type !== "meta" || meta.value === void 0) continue;
+      const property = meta.properties["property"];
+      const refines = meta.properties["refines"];
+      if (!property || !refines) continue;
+      const target = entries.find((t) => t.id === refines.slice(1));
+      if (!target) continue;
+      if (property === "identifier-type") {
+        target.identifierType = meta.value;
+        if (meta.properties["scheme"]) target.scheme = meta.properties["scheme"];
+      } else {
+        onRefinement == null ? void 0 : onRefinement(target, property, meta.value);
+      }
+    }
+    return entries;
+  }
+  /**
+   * Retrieve every `dc:identifier` entry, returned as found.
+   *
+   * Values are not interpreted. Any refining `identifier-type` meta (spec
+   * D.3.8) or legacy `opf:scheme` attribute is surfaced on the entry, but no
+   * parsing of the value itself is attempted. To read `dc:source` entries, use
+   * {@link getSources}.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async getIdentifiers() {
+    const metadata = await this.getMetadata();
+    return Epub.collectDcEntries(metadata, "dc:identifier");
+  }
+  /**
+   * Retrieve every `dc:source` entry, returned as found.
+   *
+   * Like {@link getIdentifiers}, values are not interpreted. In addition to a
+   * refining `identifier-type`, a refining `source-of` meta (spec D.3.11) is
+   * surfaced as `sourceOf`.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+   */
+  async getSources() {
+    const metadata = await this.getMetadata();
+    return Epub.collectDcEntries(
+      metadata,
+      "dc:source",
+      (source, property) => {
+        if (property === "source-of") {
+          source.isPageBreakSource = true;
+        }
+      }
+    );
+  }
+  /**
+   * Retrieve the `pageBreakSource` property (EPUB 3.4, spec D.2.9), the
+   * publication-level source for the source of its page break markers.
+   *
+   * This property replaces the refining `source-of="pagination"` meta (spec
+   * D.3.11), see {@link EpubSource.sourceOf}. If no `pageBreakSource` property is found,
+   * we fall back to finding a `dc:source` with a `source-of="pagination"` refinement.
+   *
+   * @link https://www.w3.org/TR/epub/#pageBreakSource
+   */
+  async getPageBreakSource() {
+    const entry = await this.findMetadataItem(
+      (item) => item.type === "meta" && item.properties["property"] === "pageBreakSource" && !!item.value
+    );
+    if (entry) {
+      return {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        value: entry.value,
+        id: entry.id,
+        identifierType: void 0,
+        scheme: void 0,
+        isPageBreakSource: true
+      };
+    }
+    const sources = await this.getSources();
+    const source = sources.find((source2) => source2.isPageBreakSource);
+    if (source) {
+      return source;
+    }
+    return null;
+  }
+  /**
+   * Set the `pageBreakSource` property (EPUB 3.4, spec D.2.9), or remove it when
+   * passed null. Replaces an existing `pageBreakSource` meta if present.
+   *
+   * Pass `none` to indicate the pagination is unique to this publication.
+   *
+   * @link https://www.w3.org/TR/epub/#pageBreakSource
+   */
+  async setPageBreakSource(value) {
+    if (value === null) {
+      await this.removeMetadata(
+        (item) => item.properties["property"] === "pageBreakSource"
+      );
+      return;
+    }
+    await this.replaceMetadata(
+      (item) => item.properties["property"] === "pageBreakSource",
+      { type: "meta", properties: { property: "pageBreakSource" }, value }
+    );
+  }
+  /**
+   * Replace the publication's `dc:identifier` entries.
+   *
+   * This replaces ALL existing `dc:identifier` elements except the publication's
+   * unique identifier (the one referenced by the package element's
+   * `unique-identifier` attribute), which is always preserved and must not be
+   * included in the provided list. If included anyway, it is ignored. See
+   * {@link setUniqueIdentifier} to change it.
+   *
+   * Identifiers are placed in the order they are provided.
+   *
+   * `dc:source` entries are not touched, use {@link setSources} for those.
+   *
+   * When an entry has an `identifierType`, it is written in the refining form
+   * (a `meta` with `property="identifier-type"`, carrying the `scheme`
+   * attribute when provided). An entry with only a `scheme` is written using
+   * the legacy `opf:scheme` attribute.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   */
+  async setIdentifiers(identifiers) {
+    const uniqueId = await this.getUniqueIdentifierId();
+    await this.withPackage((packageElement) => {
+      var _a;
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const children = Epub.getXmlChildren(metadata);
+      const removedIds = /* @__PURE__ */ new Set();
+      for (let i = children.length - 1; i >= 0; i--) {
+        const node = children[i];
+        if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "dc:identifier") {
+          continue;
+        }
+        const id = (_a = node[":@"]) == null ? void 0 : _a["@_id"];
+        if (id && id === uniqueId) {
+          continue;
+        }
+        if (id) {
+          removedIds.add(id);
+        }
+        children.splice(i, 1);
+      }
+      Epub.removeRefiningMetas(children, removedIds, ["identifier-type"]);
+      for (const identifier of identifiers) {
+        if (identifier.id && identifier.id === uniqueId) continue;
+        const id = identifier.id ?? (identifier.identifierType !== void 0 ? (0, import_nanoid.nanoid)() : void 0);
+        children.push(
+          Epub.createXmlElement(
+            "dc:identifier",
+            {
+              ...id && { id },
+              ...identifier.scheme && identifier.identifierType === void 0 && {
+                "opf:scheme": identifier.scheme
+              }
+            },
+            [Epub.createXmlTextNode(identifier.value)]
+          )
+        );
+        if (identifier.identifierType !== void 0 && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              {
+                refines: `#${id}`,
+                property: "identifier-type",
+                ...identifier.scheme && { scheme: identifier.scheme }
+              },
+              [Epub.createXmlTextNode(identifier.identifierType)]
+            )
+          );
+        }
+      }
+    });
+  }
+  /**
+   * Remove `meta` refinements pointing at any of the given ids,
+   * restricted to the given `property` values as a cleanup step
+   * Mutates `children` in place.
+   */
+  static removeRefiningMetas(children, ids, properties) {
+    var _a, _b, _c;
+    for (let i = children.length - 1; i >= 0; i--) {
+      const node = children[i];
+      if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "meta") {
+        continue;
+      }
+      const property = (_a = node[":@"]) == null ? void 0 : _a["@_property"];
+      if (!property || !properties.includes(property)) continue;
+      const refines = (_c = (_b = node[":@"]) == null ? void 0 : _b["@_refines"]) == null ? void 0 : _c.slice(1);
+      if (refines && ids.has(refines)) {
+        children.splice(i, 1);
+      }
+    }
+  }
+  /**
+   * Replace the publication's `dc:source` entries.
+   *
+   * This replaces ALL existing `dc:source` elements (and their refining
+   * `identifier-type` / `source-of` metas). `dc:identifier` entries are not
+   * touched; use {@link setIdentifiers} for those. Pass an empty array to
+   * remove all sources.
+   *
+   * When an entry has an `identifierType`, it is written in the refining form.
+   * A `sourceOf` value is written as a refining `source-of` meta (spec D.3.11).
+   * An entry with only a `scheme` uses the legacy `opf:scheme` attribute.
+   *
+   * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+   */
+  async setSources(sources) {
+    await this.withPackage((packageElement) => {
+      var _a;
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const children = Epub.getXmlChildren(metadata);
+      const removedIds = /* @__PURE__ */ new Set();
+      for (let i = children.length - 1; i >= 0; i--) {
+        const node = children[i];
+        if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "dc:source") {
+          continue;
+        }
+        const id = (_a = node[":@"]) == null ? void 0 : _a["@_id"];
+        if (id) {
+          removedIds.add(id);
+        }
+        children.splice(i, 1);
+      }
+      Epub.removeRefiningMetas(children, removedIds, [
+        "identifier-type",
+        "source-of"
+      ]);
+      for (const source of sources) {
+        const needsId = source.identifierType !== void 0 || source.isPageBreakSource;
+        const id = source.id ?? (needsId ? (0, import_nanoid.nanoid)() : void 0);
+        children.push(
+          Epub.createXmlElement(
+            "dc:source",
+            {
+              ...id && { id },
+              ...source.scheme && source.identifierType === void 0 && {
+                "opf:scheme": source.scheme
+              }
+            },
+            [Epub.createXmlTextNode(source.value)]
+          )
+        );
+        if (source.identifierType !== void 0 && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              {
+                refines: `#${id}`,
+                property: "identifier-type",
+                ...source.scheme && { scheme: source.scheme }
+              },
+              [Epub.createXmlTextNode(source.identifierType)]
+            )
+          );
+        }
+        if (source.isPageBreakSource && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              { refines: `#${id}`, property: "source-of" },
+              [Epub.createXmlTextNode("pagination")]
+            )
+          );
+        }
+      }
+    });
+  }
   /**
    * Even "EPUB 3" publications sometimes still only use the
    * EPUB 2 specification for identifying the cover image.

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import 'fast-xml-parser';
 export { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind } from './adapters/interface.cjs';
-export { A as AlternateScript, C as Collection, e as DcCreator, D as DcSubject, f as DublinCore, E as ElementName, m as Epub, Epub2UpgradeOptions, o as EpubFactory, n as EpubInstanceFor, d as EpubMetadata, l as EpubReadOnlyError, j as EpubReader, k as EpubVersionError, F as FromOptions, I as InMemoryEpubReader, Landmark, M as ManifestItem, c as MetadataEntry, h as Navigation, N as NavigationItem, g as NavigationList, i as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.cjs';
+export { A as AlternateScript, C as Collection, g as DcCreator, D as DcSubject, h as DublinCore, E as ElementName, o as Epub, Epub2UpgradeOptions, q as EpubFactory, e as EpubIdentifier, p as EpubInstanceFor, d as EpubMetadata, n as EpubReadOnlyError, l as EpubReader, f as EpubSource, m as EpubVersionError, F as FromOptions, I as InMemoryEpubReader, Landmark, M as ManifestItem, c as MetadataEntry, j as Navigation, N as NavigationItem, i as NavigationList, k as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.cjs';
 export { MemoryAdapter, MemoryAdapterOptions } from './adapters/memory.cjs';
 export { TmpFsAdapter } from './adapters/tmpfs.cjs';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import 'fast-xml-parser';
 export { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind } from './adapters/interface.js';
-export { A as AlternateScript, C as Collection, e as DcCreator, D as DcSubject, f as DublinCore, E as ElementName, m as Epub, Epub2UpgradeOptions, o as EpubFactory, n as EpubInstanceFor, d as EpubMetadata, l as EpubReadOnlyError, j as EpubReader, k as EpubVersionError, F as FromOptions, I as InMemoryEpubReader, Landmark, M as ManifestItem, c as MetadataEntry, h as Navigation, N as NavigationItem, g as NavigationList, i as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.js';
+export { A as AlternateScript, C as Collection, g as DcCreator, D as DcSubject, h as DublinCore, E as ElementName, o as Epub, Epub2UpgradeOptions, q as EpubFactory, e as EpubIdentifier, p as EpubInstanceFor, d as EpubMetadata, n as EpubReadOnlyError, l as EpubReader, f as EpubSource, m as EpubVersionError, F as FromOptions, I as InMemoryEpubReader, Landmark, M as ManifestItem, c as MetadataEntry, j as Navigation, N as NavigationItem, i as NavigationList, k as PackageElement, P as ParsedXml, X as XmlElement, b as XmlNode, a as XmlTextNode } from './upgrade.js';
 export { MemoryAdapter, MemoryAdapterOptions } from './adapters/memory.js';
 export { TmpFsAdapter } from './adapters/tmpfs.js';