@storyteller-platform/epub 0.6.2 → 0.7.0

package/dist/upgrade.d.ts

@@ -87,6 +87,31 @@ interface DcSubject {
     authority: string;
     term: string;
 }
+interface EpubIdentifier {
+    value: string;
+    id?: string | undefined;
+    /** the value of a refining `identifier-type` meta, if present */
+    identifierType?: string | undefined;
+    /** the `scheme` of a refining `identifier-type` meta, or a legacy `opf:scheme` attribute */
+    scheme?: string | undefined;
+}
+interface EpubSource {
+    value: string;
+    id?: string | undefined;
+    /** the value of a refining `identifier-type` meta, if present */
+    identifierType?: string | undefined;
+    /** the `scheme` of a refining `identifier-type` meta, or a legacy `opf:scheme` attribute */
+    scheme?: string | undefined;
+    /**
+     * whether this source has a `source-of="pagination"` refinement
+     * or of a `<meta property="pageBreakSource">` element
+     *
+     * as of EPUB 3.4 `source-of` is advised-deprecated in favour of the
+     * publication-level `pageBreakSource` property. if you want to
+     * be sure to get the source of pagination, use {@link Epub.getPageBreakSource}
+     */
+    isPageBreakSource?: boolean | undefined;
+}
 interface AlternateScript {
     name: string;
     locale: Intl.Locale;
@@ -140,7 +165,7 @@ interface FromOptions {
  * Read-only view of an EPUB
  * Returned by Epub.using(MemoryAdapter).from(...) and by Epub.from(path, { readonly: true })
  */
-type EpubReader = Pick<Epub, "storage" | "getManifest" | "getVersion" | "getLayout" | "getBaseDirection" | "getMetadata" | "findMetadataItem" | "findAllMetadataItems" | "getIdentifier" | "getTitle" | "getSubtitle" | "getTitles" | "getLanguage" | "getPublicationDate" | "getModifiedDate" | "getDescription" | "getType" | "getCreators" | "getContributors" | "getSubjects" | "getCollections" | "getPackageVocabularyPrefixes" | "getCoverImageItem" | "getCoverImage" | "getSpineItems" | "getNcxTableOfContents" | "getGuideEntries" | "getTableOfContents" | "getLandmarks" | "getPageList" | "resolveHref" | "readFileContents" | "readItemContents" | "readXhtmlItemContents" | "getItemArchiveLength" | "discardAndClose"> & Disposable;
+type EpubReader = Pick<Epub, "storage" | "findMetadataItem" | "findAllMetadataItems" | "resolveHref" | "readFileContents" | "readItemContents" | "readXhtmlItemContents" | "discardAndClose" | Extract<keyof Epub, `get${string}`>> & Disposable;
 /**
  * Readonly Epub-instance backed by an in-memory zip handle
  * Returned by `Epub.using(MemoryAdapter).from(...)`
@@ -366,7 +391,7 @@ declare class Epub {
      */
     findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}` | `?${string}`;
+        type: `?${string}` | `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}`;
         properties: {
             [k: string]: string;
         };
@@ -378,7 +403,7 @@ declare class Epub {
      */
     findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}` | `?${string}`;
+        type: `?${string}` | `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}`;
         properties: {
             [k: string]: string;
         };
@@ -398,12 +423,15 @@ declare class Epub {
      */
     getMetadata(): Promise<EpubMetadata>;
     /**
-     * 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.
      */
     getIdentifier(): Promise<string | null>;
     /**
@@ -413,8 +441,130 @@ declare class Epub {
      * Otherwise creates a new element
      *
      * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     *
+     * @deprecated Use {@link setUniqueIdentifier} instead.
      */
     setIdentifier(identifier: string): Promise<void>;
+    /**
+     * 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
+     */
+    getUniqueIdentifier(): Promise<string | 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
+     */
+    setUniqueIdentifier(identifier: string): Promise<void>;
+    /**
+     * 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
+     */
+    getUniqueIdentifierId(): Promise<string | 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`).
+     */
+    private static collectDcEntries;
+    /**
+     * 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
+     */
+    getIdentifiers(): Promise<EpubIdentifier[]>;
+    /**
+     * 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
+     */
+    getSources(): Promise<EpubSource[]>;
+    /**
+     * 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
+     */
+    getPageBreakSource(): Promise<EpubSource | 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
+     */
+    setPageBreakSource(value: string | null): Promise<void>;
+    /**
+     * 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
+     */
+    setIdentifiers(identifiers: EpubIdentifier[]): Promise<void>;
+    /**
+     * Remove `meta` refinements pointing at any of the given ids,
+     * restricted to the given `property` values as a cleanup step
+     * Mutates `children` in place.
+     */
+    private static removeRefiningMetas;
+    /**
+     * 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
+     */
+    setSources(sources: EpubSource[]): Promise<void>;
     /**
      * Even "EPUB 3" publications sometimes still only use the
      * EPUB 2 specification for identifying the cover image.
@@ -1029,4 +1179,4 @@ declare class EpubFactory<A extends EpubStorageAdapterClass> {
     upgrade(path: string, options?: Epub2UpgradeOptions): Promise<EpubInstanceFor<A>>;
 }
 
-export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type FromOptions as F, type InMemoryEpubReader as I, type Landmark, type ManifestItem as M, type NavigationItem as N, type ParsedXml as P, type XmlElement as X, type XmlTextNode as a, type XmlNode as b, buildNavDocument, buildTocOl, type MetadataEntry as c, chooseNavHref, collectManifestProperties, type EpubMetadata as d, type DcCreator as e, extractGuideLandmarks, type DublinCore as f, fixFontMimeTypes, type NavigationList as g, type Navigation as h, type PackageElement as i, type EpubReader as j, EpubVersionError as k, EpubReadOnlyError as l, Epub as m, type EpubInstanceFor as n, EpubFactory as o, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };
+export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type FromOptions as F, type InMemoryEpubReader as I, type Landmark, type ManifestItem as M, type NavigationItem as N, type ParsedXml as P, type XmlElement as X, type XmlTextNode as a, type XmlNode as b, buildNavDocument, buildTocOl, type MetadataEntry as c, chooseNavHref, collectManifestProperties, type EpubMetadata as d, type EpubIdentifier as e, extractGuideLandmarks, type EpubSource as f, fixFontMimeTypes, type DcCreator as g, type DublinCore as h, type NavigationList as i, type Navigation as j, type PackageElement as k, type EpubReader as l, EpubVersionError as m, EpubReadOnlyError as n, Epub as o, type EpubInstanceFor as p, EpubFactory as q, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storyteller-platform/epub",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "type": "module",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,8 +23,9 @@
     "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",
-    "test": "tsx -C @storyteller --test *.test.ts",
-    "test:watch": "tsx -C @storyteller --test --watch *.test.ts",
+    "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",
     "prepack": "yarn build"
   },
   "devDependencies": {
@@ -35,7 +36,6 @@
     "@types/node": "^24.0.0",
     "@types/yauzl-promise": "^4",
     "@types/yazl": "^3",
-    "epubchecker": "^5.2.1",
     "eslint": "^8.0.0",
     "markdown-toc": "^1.2.0",
     "remark-toc": "^9.0.0",