@storyteller-platform/epub 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,5 +1,1161 @@
-import 'fast-xml-parser';
-export { AdapterOptions, EpubListEntry, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageCapabilities, EpubStorageKind } from './adapters/interface.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';
+import { XMLParser } from "fast-xml-parser";
+import type { AdapterOptions, EpubStorageAdapter, EpubStorageAdapterClass, EpubStorageKind } from "./adapters/interface.ts";
+import * as Upgrade from "./upgrade.ts";
+export type { EpubStorageKind } from "./adapters/interface.ts";
+export { type AdapterOptions, type EpubListEntry, type EpubStorageAdapter, type EpubStorageAdapterClass, type EpubStorageCapabilities, } from "./adapters/interface.ts";
+export { MemoryAdapter, type MemoryAdapterOptions } from "./adapters/memory.ts";
+export { TmpFsAdapter } from "./adapters/tmpfs.ts";
+declare global {
+    namespace Intl {
+        interface Locale {
+            textInfo: {
+                direction: "rtl" | "ltr";
+            };
+        }
+    }
+}
+type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+type QuestionMark = "?";
+/** A valid name for an XML element (must start with a letter) */
+export type ElementName = `${Letter | Uppercase<Letter> | QuestionMark}${string}`;
+type PropertyPrefix = "@_";
+/** An XML element */
+export type XmlElement<Name extends ElementName = ElementName> = {
+    ":@"?: Record<`${PropertyPrefix}${string}`, string>;
+} & {
+    [key in Name]: ParsedXml;
+};
+/** A text node in an XML document */
+export type XmlTextNode = {
+    "#text": string;
+};
+/** A valid XML node. May be either an element or a text node. */
+export type XmlNode = XmlElement | XmlTextNode;
+/** An XML structure */
+export type ParsedXml = Array<XmlNode>;
+export type ManifestItem = {
+    id: string;
+    href: string;
+    mediaType?: string | undefined;
+    fallback?: string | undefined;
+    mediaOverlay?: string | undefined;
+    properties?: string[] | undefined;
+};
+export type MetadataEntry = {
+    id?: string | undefined;
+    type: ElementName;
+    properties: Record<string, string>;
+    value: string | undefined;
+};
+export type EpubMetadata = MetadataEntry[];
+export interface DcSubject {
+    value: string;
+    authority: string;
+    term: string;
+}
+export 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;
+}
+export 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;
+}
+export interface AlternateScript {
+    name: string;
+    locale: Intl.Locale;
+}
+export interface DcCreator {
+    name: string;
+    role?: string;
+    roleScheme?: string;
+    fileAs?: string;
+    alternateScripts?: AlternateScript[];
+}
+export interface DublinCore {
+    title: string;
+    language: Intl.Locale;
+    identifier: string;
+    date?: Date;
+    subjects?: Array<string | DcSubject>;
+    creators?: DcCreator[];
+    contributors?: DcCreator[];
+    type?: string;
+}
+export interface Collection {
+    name: string;
+    type?: string;
+    position?: string;
+}
+export interface NavigationItem {
+    title: string;
+    href?: string;
+    children?: NavigationList;
+}
+export type NavigationList = NavigationItem[];
+export interface Navigation {
+    title?: string;
+    children: NavigationList;
+}
+interface GuideItem {
+    href: string;
+    title: string;
+    type: string;
+}
+export type PackageElement = XmlElement<"package">;
+export interface FromOptions {
+    /**
+     * when true, mutation methods throw {@link EpubReadOnlyError} at runtime
+     * @default false
+     */
+    readonly?: boolean;
+}
+/**
+ * Read-only view of an EPUB
+ * Returned by Epub.using(MemoryAdapter).from(...) and by Epub.from(path, { readonly: true })
+ */
+export 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(...)`
+ */
+export type InMemoryEpubReader = EpubReader & {
+    readonly storage: "in-memory";
+};
+export declare class EpubVersionError extends Error {
+}
+export declare class EpubReadOnlyError extends Error {
+}
+/**
+ * A single EPUB instance.
+ *
+ * The entire EPUB contents will be read into memory.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * import { Epub, getBody, findByName, textContent } from '@storyteller-platform/epub';
+ *
+ * const epub = await Epub.from('./path/to/book.epub');
+ * const title = await epub.getTitle();
+ * const spineItems = await epub.getSpineItems();
+ * const chptOne = spineItems[0];
+ * const chptOneXml = await epub.readXhtmlItemContents(chptOne.id);
+ *
+ * const body = getBody(chptOneXml);
+ * const h1 = Epub.findXmlChildByName('h1', body);
+ * const headingText = textContent(h1);
+ *
+ * await epub.setTitle(headingText);
+ * await epub.writeToFile('./path/to/updated.epub');
+ * await epub.close();
+ * ```
+ *
+ * @link https://www.w3.org/TR/epub-33/
+ */
+export declare class Epub {
+    protected adapterClass: EpubStorageAdapterClass;
+    protected adapter: EpubStorageAdapter;
+    protected inputPath: string | undefined;
+    protected readonlyOverride: boolean;
+    static xmlParser: XMLParser;
+    static xhtmlParser: XMLParser;
+    static xmlBuilder: import("fast-xml-builder").XMLBuilder;
+    static xhtmlBuilder: import("fast-xml-builder").XMLBuilder;
+    /**
+     * Format a duration, provided as a number of seconds, as
+     * a SMIL clock value, to be used for Media Overlays.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-duration
+     */
+    static formatSmilDuration(duration: number): string;
+    /**
+     * Given an XML structure representing a complete XHTML document,
+     * add a `link` element to the `head` of the document.
+     *
+     * This method modifies the provided XML structure.
+     */
+    static addLinkToXhtmlHead(xml: ParsedXml, link: {
+        rel: string;
+        href: string;
+        type: string;
+    }): void;
+    /**
+     * Given an XML structure representing a complete XHTML document,
+     * return the sub-structure representing the children of the
+     * document's body element.
+     */
+    static getXhtmlBody(xml: ParsedXml): ParsedXml;
+    static createXmlElement<Name extends ElementName>(name: Name, properties: Record<string, string>, children?: XmlNode[]): XmlElement<Name>;
+    static createXmlTextNode(text: string): XmlTextNode;
+    /**
+     * Given an XML structure representing a complete XHTML document,
+     * return a string representing the concatenation of all text nodes
+     * in the document.
+     */
+    static getXhtmlTextContent(xml: ParsedXml): string;
+    /**
+     * Given an XMLElement, return its attributes.
+     */
+    static getXmlAttributes(element: XmlElement): Record<string, string>;
+    /**
+     * Given an XMLElement, return its tag name.
+     */
+    static getXmlElementName<Name extends ElementName>(element: XmlElement<Name>): Name;
+    /**
+     * Given an XMLElement, return a list of its children
+     */
+    static getXmlChildren<Name extends ElementName>(element: XmlElement<Name>): ParsedXml;
+    static replaceXmlChildren<Name extends ElementName>(element: XmlElement<Name>, children: XmlNode[]): void;
+    /**
+     * Given an XML structure, find the first child matching
+     * the provided name and optional filter.
+     */
+    static findXmlChildByName<Name extends ElementName>(name: Name, xml: ParsedXml, filter?: (node: XmlElement<Name>) => boolean): XmlElement<Name> | undefined;
+    /**
+     * Given an XML structure, find the first descendant matching
+     * the provided name and optional filter.
+     *
+     * Will perform a breadth first search for the element, returning
+     * the highest element in the tree matching the name and filter.
+     */
+    static findXmlDescendantByName<Name extends ElementName>(name: Name, xml: ParsedXml, filter?: (node: XmlElement<Name>) => boolean): XmlElement<Name> | undefined;
+    /**
+     * Given an XMLNode, determine whether it represents
+     * a text node or an XML element.
+     */
+    static isXmlTextNode(node: XmlNode): node is XmlTextNode;
+    private rootfile;
+    private manifest;
+    private spine;
+    private packageMutex;
+    /**
+     * Storage backend kind in use for this instance
+     *
+     * Public so callers can declare type-level requirements via {@link InMemoryEpubReader}
+     * Orthogonal to the read-only / writable axis (controlled by `readonlyOverride`
+     * and the adapter's capability bag)
+     */
+    readonly storage: EpubStorageKind;
+    /**
+     * Prefer the static factories ({@link Epub.using}, {@link Epub.from},
+     * {@link Epub.create}, {@link Epub.upgrade}) over calling this constructor
+     * directly. It's public so {@link EpubFactory} can construct instances; nothing
+     * else should need to.
+     */
+    constructor(adapterClass: EpubStorageAdapterClass, adapter: EpubStorageAdapter, inputPath: string | undefined, readonlyOverride?: boolean);
+    /**
+     * Runtime guard for mutation methods
+     */
+    private assertWritable;
+    /**
+     * Construct a new EPUB on a writable backend, optionally seeded
+     * with the provided metadata. Equivalent to
+     * `Epub.using(TmpFsAdapter).create(...)`.
+     *
+     * @param dublinCore Core metadata terms
+     * @param additionalMetadata An array of additional metadata entries
+     */
+    static create(path: string, dublinCore: DublinCore, additionalMetadata?: EpubMetadata): Promise<Epub>;
+    /**
+     * Specify the storage backend to use for the EPUB
+     *
+     * The returned factory exposes `from`, `create`, and `upgrade`,
+     * which route through the supplied adapter.
+     *
+     * @example
+     * ```ts
+     * using epub = await Epub.using(TmpFsAdapter).from(path)
+     * using reader = await Epub.using(MemoryAdapter).from(buffer, { cache: false })
+     * ```
+     */
+    static using<A extends EpubStorageAdapterClass>(adapterClass: A): EpubFactory<A>;
+    /**
+     * Open an existing EPUB publication, extracting it to a temp directory
+     * so writes can mutate the unpacked tree and rezip with `saveAndClose`.
+     *
+     * Pass `{ readonly: true }` to gate mutations at runtime.
+     *
+     * prefer `Epub.using(TmpFsAdapter).from(path)` (or
+     *   `Epub.using(MemoryAdapter).from(path)` for read-only, in-memory access)
+     * @throws {EpubVersionError} when the archive is not a valid EPUB 3
+     */
+    static from(pathOrData: string | Uint8Array): Promise<Epub>;
+    static from(pathOrData: string | Uint8Array, options: FromOptions & {
+        readonly: true;
+    }): Promise<EpubReader>;
+    static from(pathOrData: string | Uint8Array, options?: FromOptions): Promise<Epub | EpubReader>;
+    static assertEpub3(epub: Epub): Promise<void>;
+    copy(path?: string): Promise<Epub>;
+    private removeEntry;
+    /**
+     * Length of the underlying archive entry for a manifest item, in bytes
+     * Necessary to compute the readium page count which is for COMPRESSED content
+     * @see {@link https://github.com/readium/architecture/issues/123}
+     */
+    getItemArchiveLength(id: string): Promise<number>;
+    getRootfile(): Promise<string>;
+    private getPackageDocument;
+    getPackageElement(): Promise<XmlElement<"package">>;
+    /**
+     * Safely modify the package document, without race conditions.
+     *
+     * Since the reading the package document is an async process,
+     * multiple simultaneously dispatched function calls that all
+     * attempt to modify it can clobber each other's changes. This
+     * method uses a mutex to ensure that each update runs exclusively.
+     *
+     * @param producer The function to update the package document. If
+     *    it returns a new package document, that will be persisted, otherwise
+     *    it will be assumed that the package document was modified in place.
+     */
+    withPackage(producer: ((packageElement: PackageElement) => void) | ((packageElement: PackageElement) => PackageElement) | ((packageElement: PackageElement) => Promise<PackageElement>) | ((packageElement: PackageElement) => Promise<void>)): Promise<void>;
+    /**
+     * Retrieve the manifest for the Epub.
+     *
+     * This is represented as a map from each manifest items'
+     * id to the rest of its properties.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+     */
+    getManifest(): Promise<Record<string, ManifestItem>>;
+    /**
+     * Returns the first index in the metadata element's children array
+     * that matches the provided predicate.
+     *
+     * Note: This may technically be different than the index in the
+     * getMetadata() array, as it includes non-metadata nodes, like
+     * text nodes. These are technically not allowed, but may exist,
+     * nonetheless. As consumers only ever see the getMetadata()
+     * array, this method is only meant to be used internally.
+     */
+    private findMetadataIndex;
+    /**
+     * Returns the item in the metadata element's children array
+     * that matches the provided predicate.
+     */
+    findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<{
+        id: string | undefined;
+        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;
+        };
+        value: string | undefined;
+    } | null>;
+    /**
+     * Returns the item in the metadata element's children array
+     * that matches the provided predicate.
+     */
+    findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<{
+        id: string | undefined;
+        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;
+        };
+        value: string | undefined;
+    }[]>;
+    private static parseMetadataItem;
+    /**
+     * Retrieve the metadata entries for the Epub.
+     *
+     * This is represented as an array of metadata entries,
+     * in the order that they're presented in the Epub package document.
+     *
+     * For more useful semantic representations of metadata, use
+     * specific methods such as `getTitle()` and `getAuthors()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    getMetadata(): Promise<EpubMetadata>;
+    /**
+     * 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>;
+    /**
+     * Set the dc:identifier metadata element with the provided string.
+     *
+     * Updates the existing dc:identifier element if one exists.
+     * 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.
+     * This is a private method that is used as a fallback if
+     * we fail to find the cover image according to the EPUB 3
+     * spec.
+     */
+    private getEpub2CoverImage;
+    /**
+     * Retrieve the cover image manifest item.
+     *
+     * This does not return the actual image data. To
+     * retrieve the image data, pass this item's id to
+     * epub.readItemContents, or use epub.getCoverImage()
+     * instead.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-cover-image
+     */
+    getCoverImageItem(): Promise<ManifestItem | null>;
+    /**
+     * Retrieve the cover image data as a byte array.
+     *
+     * This does not include, for example, the cover image's
+     * filename or mime type. To retrieve the image manifest
+     * item, use epub.getCoverImageItem().
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-cover-image
+     */
+    getCoverImage(): Promise<Uint8Array<ArrayBufferLike> | null>;
+    /**
+     * Set the cover image for the EPUB.
+     *
+     * Adds a manifest item with the `cover-image` property, per
+     * the EPUB 3 spec, and then writes the provided image data to
+     * the provided href within the publication.
+     */
+    setCoverImage(href: string, data: Uint8Array): Promise<void>;
+    /**
+     * Retrieve the publication date from the dc:date element
+     * in the EPUB metadata as a Date object.
+     *
+     * If there is no dc:date element, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcdate
+     */
+    getPublicationDate(): Promise<Date | null>;
+    /**
+     * Set the dc:date metadata element with the provided date.
+     *
+     * Updates the existing dc:date element if one exists.
+     * Otherwise creates a new element
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcdate
+     */
+    setPublicationDate(date: Date): Promise<void>;
+    /**
+     * Retrieve the modified date from the dcterms:modified metadata
+     * in the EPUB metadata as a Date object.
+     *
+     * If there is no meta element with dcterms:modified, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-metadata-last-modified
+     */
+    getModifiedDate(): Promise<Date | null>;
+    /**
+     * Retrieve the layout from the rendition:layout meta element
+     * in the EPUB metadata.
+     *
+     * If there is no meta element, returns 'reflowable'.
+     *
+     * @link https://www.w3.org/TR/epub-33/#layout
+     */
+    getLayout(): Promise<"reflowable" | "pre-paginated">;
+    /**
+     * Retrieve the base direction from the package element.
+     *
+     * If there is no `dir` attribute on the package element,
+     * returns 'auto'.
+     *
+     * @link https://www.w3.org/TR/epub-33/#attrdef-dir
+     */
+    getBaseDirection(): Promise<"ltr" | "rtl" | "auto">;
+    /**
+     * Set the dc:type metadata element.
+     *
+     * Updates the existing dc:type element if one exists.
+     * Otherwise creates a new element.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctype
+     */
+    setType(type: string): Promise<void>;
+    /**
+     * Retrieve the publication type from the dc:type element
+     * in the EPUB metadata.
+     *
+     * If there is no dc:type element, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctype
+     */
+    getType(): Promise<MetadataEntry | null>;
+    /**
+     * Add a subject to the EPUB metadata.
+     *
+     * @param subject May be a string representing just a schema-less
+     *  subject name, or a DcSubject object
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
+     */
+    addSubject(subject: string | DcSubject): Promise<void>;
+    /**
+     * Remove a subject from the EPUB metadata.
+     *
+     * Removes the subject at the provided index. This index
+     * refers to the array returned by `epub.getSubjects()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    removeSubject(index: number): Promise<void>;
+    /**
+     * Retrieve the list of subjects for this EPUB.
+     *
+     * Subjects without associated authority and term metadata
+     * will be returned as strings. Otherwise, they will
+     * be represented as DcSubject objects, with a value,
+     * authority, and term.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
+     */
+    getSubjects(): Promise<(string | DcSubject)[]>;
+    /**
+     * Retrieve the Epub's language as specified in its
+     * package document metadata.
+     *
+     * If no language metadata is specified, returns null.
+     * Returns the language as an Intl.Locale instance.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
+     */
+    getLanguage(): Promise<Intl.Locale | null>;
+    /**
+     * Update the Epub's language metadata entry.
+     *
+     * Updates the existing dc:language element if one exists.
+     * Otherwise creates a new element
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
+     */
+    setLanguage(locale: Intl.Locale): Promise<void>;
+    /**
+     * Retrieve the title of the Epub.
+     *
+     * @param main Optional - whether to return only the first title segment
+     *  if multiple are found. Otherwise, will follow the spec to combine title
+     *  segments
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    getTitle(expanded?: boolean): Promise<string | null>;
+    /**
+     * Retrieve the subtitle of the Epub, if it exists.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    getSubtitle(): Promise<string | null>;
+    /**
+     * Retrieve all title entries of the Epub.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    getTitles(): Promise<{
+        title: string;
+        type: string | null;
+    }[]>;
+    /**
+     * Update the Epub's description metadata entry.
+     *
+     * Updates the existing dc:description element if one exists.
+     * Otherwise creates a new element. Any non-ASCII symbols,
+     * `&`, `<`, `>`, `"`, `'`, and `\``` will be encoded as HTML entities.
+     */
+    setDescription(description: string): Promise<void>;
+    /**
+     * Retrieve the Epub's description as specified in its
+     * package document metadata.
+     *
+     * If no description metadata is specified, returns null.
+     * Returns the description as a string. Descriptions may
+     * include HTML markup.
+     */
+    getDescription(): Promise<string | null>;
+    /**
+     * Return the set of custom vocabulary prefixes set on this publication's
+     * root package element.
+     *
+     * Returns a map from prefix to URI
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
+     */
+    getPackageVocabularyPrefixes(): Promise<Record<string, string>>;
+    /**
+     * Set a custom vocabulary prefix on the root package element.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
+     */
+    setPackageVocabularyPrefix(prefix: string, uri: string): Promise<void>;
+    /**
+     * Set the title of the Epub.
+     *
+     * This will replace all existing dc:title elements with
+     * this title. It will be given title-type "main".
+     *
+     * To set specific titles and their types, use epub.setTitles().
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    setTitle(title: string): Promise<void>;
+    setTitles(entries: {
+        title: string;
+        type: string | null;
+    }[]): Promise<void>;
+    /**
+     * Retrieve the list of collections.
+     */
+    getCollections(): Promise<Collection[]>;
+    /**
+     * Add a collection to the EPUB metadata.
+     *
+     * If index is provided, the collection will be placed at
+     * that index in the list of collections. Otherwise, it
+     * will be added to the end of the list.
+     */
+    addCollection(collection: Collection, index?: number): Promise<void>;
+    /**
+     * Remove a collection from the EPUB metadata.
+     *
+     * Removes the collection at the provided index. This index
+     * refers to the array returned by `epub.getCollections()`.
+     */
+    removeCollection(index: number): Promise<void>;
+    /**
+     * Retrieve the list of creators.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    getCreators(type?: "creator" | "contributor"): Promise<DcCreator[]>;
+    /**
+     * Retrieve the list of contributors.
+     *
+     * This is a convenience method for
+     * `epub.getCreators('contributor')`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccontributor
+     */
+    getContributors(): Promise<DcCreator[]>;
+    /**
+     * Add a creator to the EPUB metadata.
+     *
+     * If index is provided, the creator will be placed at
+     * that index in the list of creators. Otherwise, it
+     * will be added to the end of the list.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    addCreator(creator: DcCreator, index?: number, type?: "creator" | "contributor"): Promise<void>;
+    /**
+     * Remove a creator from the EPUB metadata.
+     *
+     * Removes the creator at the provided index. This index
+     * refers to the array returned by `epub.getCreators()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    removeCreator(index: number, type?: "creator" | "contributor"): Promise<void>;
+    /**
+     * Remove a contributor from the EPUB metadata.
+     *
+     * Removes the contributor at the provided index. This index
+     * refers to the array returned by `epub.getContributors()`.
+     *
+     * This is a convenience method for
+     * `epub.removeCreator(index, 'contributor')`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    removeContributor(index: number): Promise<void>;
+    /**
+     * Add a contributor to the EPUB metadata.
+     *
+     * If index is provided, the creator will be placed at
+     * that index in the list of creators. Otherwise, it
+     * will be added to the end of the list.
+     *
+     * This is a convenience method for
+     * `epub.addCreator(contributor, index, 'contributor')`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    addContributor(contributor: DcCreator, index?: number): Promise<void>;
+    private getSpine;
+    /**
+     * Retrieve the manifest items that make up the Epub's spine.
+     *
+     * The spine specifies the order that the contents of the Epub
+     * should be displayed to users by default.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+     */
+    getSpineItems(): Promise<ManifestItem[]>;
+    /**
+     * Add an item to the spine of the EPUB.
+     *
+     * If `index` is undefined, the item will be added
+     * to the end of the spine. Otherwise it will be
+     * inserted at the specified index.
+     *
+     * If the manifestId does not correspond to an item
+     * in the manifest, this will throw an error.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+     */
+    addSpineItem(manifestId: string, index?: number): Promise<void>;
+    /**
+     * Remove the spine item at the specified index.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+     */
+    removeSpineItem(index: number): Promise<void>;
+    private getNavigationChildren;
+    private getNavigation;
+    /**
+     * Returns the structured table of contents navigation document
+     * as a Navigation object.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-nav-toc
+     */
+    getTableOfContents({ resolveToRoot, }?: {
+        resolveToRoot?: boolean;
+    }): Promise<Navigation | null>;
+    /**
+     * Returns the structured landmarks navigation document
+     * as a Navigation object
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-nav-landmarks
+     */
+    getLandmarks({ resolveToRoot, }?: {
+        resolveToRoot?: boolean;
+    }): Promise<Navigation | null>;
+    /**
+     * Returns the structured page list navigation document
+     * as a Navigation object
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-nav-landmarks
+     */
+    getPageList({ resolveToRoot, }?: {
+        resolveToRoot?: boolean;
+    }): Promise<Navigation | null>;
+    /**
+     * Name the entry a resolved URL addresses.
+     *
+     * A correctly authored publication percent-encodes its hrefs, so the
+     * decoded reading is the one the spec calls for and the one we prefer.
+     * Some publications instead write the entry name verbatim, so when the two
+     * readings differ we ask the archive which one it holds. A verbatim name
+     * carrying a bare `%`, as `100%.xhtml` does, is not a valid encoding at all
+     * and can only be its own answer.
+     */
+    private entryForUrl;
+    /**
+     * Resolve an href to the name of the archive entry it addresses.
+     *
+     * @param from The entry the href appears in; it resolves against that
+     *   entry's directory
+     * @throws when the href addresses something outside the publication
+     */
+    private resolveEntry;
+    /**
+     * Returns a path-relative-scheme-less URL, relative to the
+     * container root.
+     *
+     * An href that points outside the publication, such as an external link in
+     * a navigation document, is handed back unchanged.
+     *
+     * @param href The href to resolve
+     * @param [relativeTo] Optional - The href to resolve this href relative to.
+         Use if resolving a relative href from a file other than the package document.
+     */
+    resolveHref(href: string, relativeTo?: string, { toRoot }?: {
+        toRoot?: boolean | undefined;
+    }): Promise<string>;
+    /**
+     * Retrieve the contents of a file, given its href.
+     *
+     * Optionally takes the href that this href should be resolved relative to,
+     * and an encoding parameter.
+     *
+     * @param href The href of the file to retrieve
+     * @param [relitaveTo] Optional - The href to resolve this href relative to.
+     *   Use if resolving a relative href from a file other than the package document.
+     * @param [encoding] Optional - Must be the string "utf-8". If provided,
+     *   the function will encode the data into a unicode string.
+     *   Otherwise, the data will be returned as a byte array.
+     */
+    readFileContents(href: string, relativeTo?: string): Promise<Uint8Array>;
+    readFileContents(href: string, relativeTo: string | undefined, encoding: "utf-8"): Promise<string>;
+    /**
+     * Retrieve the contents of a manifest item, given its id.
+     *
+     * @param id The id of the manifest item to retrieve
+     * @param [encoding] Optional - must be the string "utf-8". If
+     *  provided, the function will encode the data into a unicode string.
+     *  Otherwise, the data will be returned as a byte array.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
+     */
+    readItemContents(id: string): Promise<Uint8Array>;
+    readItemContents(id: string, encoding: "utf-8"): Promise<string>;
+    /**
+     * Create a new XHTML document with the given body
+     * and head.
+     *
+     * @param body The XML nodes to place in the body of the document
+     * @param head Optional - the XMl nodes to place in the head
+     * @param language Optional - defaults to the EPUB's language
+     */
+    createXhtmlDocument(body: ParsedXml, head?: ParsedXml, language?: Intl.Locale): Promise<(XmlElement<"?xml"> | XmlElement<"html">)[]>;
+    /**
+     * Retrieves the contents of an XHTML item, given its manifest id.
+     *
+     * @param id The id of the manifest item to retrieve
+     * @param [as] Optional - whether to return the parsed XML document tree,
+     *  or the concatenated text of the document. Defaults to the parsed XML tree.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-xhtml
+     */
+    readXhtmlItemContents(id: string, as?: "xhtml"): Promise<ParsedXml>;
+    readXhtmlItemContents(id: string, as: "text"): Promise<string>;
+    private writeEntryContents;
+    /**
+     * Write new contents for an existing manifest item,
+     * specified by its id.
+     *
+     * The id must reference an existing manifest item. If
+     * creating a new item, use `epub.addManifestItem()` instead.
+     *
+     * @param id The id of the manifest item to write new contents for
+     * @param contents The new contents. May be either a utf-8 encoded string
+     *  or a byte array, as determined by the encoding
+     * @param [encoding] Optional - must be the string "utf-8". If provided,
+     *  the contents will be interpreted as a unicode string. Otherwise, the
+     *  contents must be a byte array.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
+     */
+    writeItemContents(id: string, contents: Uint8Array): Promise<void>;
+    writeItemContents(id: string, contents: string, encoding: "utf-8"): Promise<void>;
+    /**
+     * Write new contents for an existing XHTML item,
+     * specified by its id.
+     *
+     * The id must reference an existing manifest item. If
+     * creating a new item, use `epub.addManifestItem()` instead.
+     *
+     * @param id The id of the manifest item to write new contents for
+     * @param contents The new contents. Must be a parsed XML tree.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-xhtml
+     */
+    writeXhtmlItemContents(id: string, contents: ParsedXml): Promise<void>;
+    removeManifestItem(id: string): Promise<void>;
+    /**
+     * Create a new manifest item and write its contents to a
+     * new entry.
+     *
+     * @param id The id of the manifest item to write new contents for
+     * @param contents The new contents. May be either a parsed XML tree
+     *  or a unicode string, as determined by the `as` argument.
+     * @param encoding Optional - whether to interpret contents as a parsed
+     *  XML tree, a unicode string, or a byte array. Defaults to a byte array.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+     * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
+     */
+    addManifestItem(item: ManifestItem, contents: ParsedXml, encoding: "xml"): Promise<void>;
+    addManifestItem(item: ManifestItem, contents: string, encoding: "utf-8"): Promise<void>;
+    addManifestItem(item: ManifestItem, contents: Uint8Array): Promise<void>;
+    /**
+     * Update the manifest entry for an existing item.
+     *
+     * To update the contents of an entry, use `epub.writeItemContents()`
+     * or `epub.writeXhtmlItemContents()`
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+     */
+    updateManifestItem(id: string, newItem: Omit<ManifestItem, "id">): Promise<void>;
+    /**
+     * Add a new metadata entry to the Epub.
+     *
+     * This method, like `epub.getMetadata()`, operates on
+     * metadata entries. For more useful semantic representations
+     * of metadata, use specific methods such as `setTitle()` and
+     * `setLanguage()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    addMetadata(entry: MetadataEntry): Promise<void>;
+    /**
+     * Replace a metadata entry with a new one.
+     *
+     * The `predicate` argument will be used to determine which entry
+     * to replace. The first metadata entry that matches the
+     * predicate will be replaced.
+     *
+     * @param predicate Calls predicate once for each metadata entry,
+     *  until it finds one where predicate returns true
+     * @param entry The new entry to replace the found entry with
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    replaceMetadata(predicate: (entry: MetadataEntry) => boolean, entry: MetadataEntry): Promise<void>;
+    /**
+     * Remove one or more metadata entries.
+     *
+     * The `predicate` argument will be used to determine which entries
+     * to remove. The all metadata entries that match the
+     * predicate will be removed.
+     *
+     * @param predicate Calls predicate once for each metadata entry,
+     *  removing any for which it returns true
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    removeMetadata(predicate: (entry: MetadataEntry) => boolean): Promise<void>;
+    /**
+     * Returns the EPUB version declared on the package element.
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Parse the NCX table of contents, if one exists, and return
+     * a tree of TocEntry nodes.
+     *
+     * Useful for both EPUB 2 publications (where the NCX is the
+     * primary navigation) and EPUB 3 publications that retain an
+     * NCX for backwards compatibility.
+     */
+    getNcxTableOfContents(): Promise<NavigationList>;
+    private parseNavPoints;
+    /**
+     * Retrieve the guide entries from the package document.
+     *
+     * The guide element is deprecated in EPUB 3 in favor of
+     * the landmarks nav, but many publications still include it.
+     */
+    getGuideEntries(): Promise<GuideItem[]>;
+    discardAndClose(): void;
+    /**
+     * Write the current contents of the Epub to a new
+     * EPUB archive on disk.
+     *
+     * When this method is called, the "dcterms:modified"
+     * meta tag is automatically updated to the current UTC
+     * timestamp.
+     */
+    saveAndClose(): Promise<void>;
+    /**
+     * Upgrade an EPUB 2 publication to EPUB 3 in place, returning a new,
+     * valid Epub 3 instance. Equivalent to
+     * `Epub.using(TmpFsAdapter).upgrade(...)`.
+     */
+    static upgrade(path: string, options?: Upgrade.Epub2UpgradeOptions): Promise<Epub>;
+    [Symbol.dispose](): void;
+}
+/**
+ * Resolves to {@link Epub} for writable adapters, {@link EpubReader} for read-only ones.
+ *
+ * The conditional pivots on `capabilities.writable`, which must be a literal
+ * `true`/`false` on the adapter class (use `as const`) for inference to work.
+ */
+export type EpubInstanceFor<A extends EpubStorageAdapterClass> = A["capabilities"]["writable"] extends true ? Epub : EpubReader;
+/**
+ * Adapter-bound factory returned by {@link Epub.using}.
+ *
+ * Mirrors the static factory surface (`from`, `create`, `upgrade`) but routes
+ * all I/O through the supplied adapter. Each method's signature degrades
+ * gracefully when the adapter doesn't support the operation: `create` and
+ * `upgrade` throw at runtime if the adapter is read-only or lacks `initEmpty`.
+ */
+export declare class EpubFactory<A extends EpubStorageAdapterClass> {
+    readonly adapterClass: A;
+    constructor(adapterClass: A);
+    /**
+     * Open an existing EPUB through this factory's adapter
+     *
+     * @throws {EpubVersionError} when the archive is not a valid EPUB 3
+     */
+    from(source: string | Uint8Array, options: FromOptions & {
+        readonly: true;
+    } & AdapterOptions<A>): Promise<EpubReader & {
+        storage: A["kind"];
+    }>;
+    from(source: string | Uint8Array, options?: FromOptions & AdapterOptions<A>): Promise<EpubInstanceFor<A> & {
+        storage: A["kind"];
+    }>;
+    /**
+     * Construct a new EPUB on this factory's adapter, optionally seeded
+     * with the provided metadata. Requires a writable adapter that
+     * implements `initEmpty` (today: {@link TmpFsAdapter}).
+     *
+     * @throws when the adapter is read-only or does not implement initEmpty
+     */
+    create(path: string, { title, language, identifier, date, subjects, type, creators, contributors, }: DublinCore, additionalMetadata?: EpubMetadata): Promise<EpubInstanceFor<A>>;
+    /**
+     * Upgrade an EPUB 2 publication to EPUB 3 in place using this
+     * factory's adapter, returning a new, valid Epub 3 instance.
+     *
+     * Performs the following transformations:
+     *  - upgrades OPF metadata to EPUB 3 conventions
+     *  - scans XHTML documents and adds manifest item properties
+     *  - parses the NCX into a TOC tree and generates a nav.xhtml
+     *  - removes the NCX file and the guide element (configurable)
+     *  - fixes common font MIME types
+     *  - bumps the package version to 3.0
+     *  - goes over each xhtml item and rewrites it using XMLParser to make sure the output is valid XHTML
+     *
+     * Requires a writable adapter. When {@link Upgrade.Epub2UpgradeOptions.outputPath}
+     * is set, the source file is copied to that path on disk first; this
+     * only makes sense for adapters whose `source` is a real fs path.
+     *
+     * @throws when the adapter is read-only
+     */
+    upgrade(path: string, options?: Upgrade.Epub2UpgradeOptions): Promise<EpubInstanceFor<A>>;
+}
+export type { Epub2UpgradeOptions, Landmark } from "./upgrade.ts";