@smoores/epub

A Node.js library for inspecting, modifying, and creating EPUB 3 publications.

• Installation
• About
  • EPUB Basics
  • What this library does
• Usage
  • Reading from a file
  • Creating from scratch
  • Adding a chapter
  • Writing to disk
  • Writing to a byte array
• Development
• API Docs

Installation

npm:

npm install @smoores/epub

yarn:

yarn add @smoores/epub

deno:

deno install npm:@smoores/epub

About

Throughout this library's documentation, there will be many references to the EPUB 3 specification. The lower level APIs exposed by this library require some knowledge of this specification. Here we will cover the very basics necessary to work with the library, but we recommend that users read through the linked specification to gain a deeper understanding of the format.

EPUB Basics

An EPUB file is a ZIP archive with a partially specified directory and file structure. Most of the metadata and content is specified as XML documents, with additional resources referenced from those XML documents.

The most important of these documents is the package document.

The package document is an XML document that consists of a set of elements that each encapsulate information about a particular aspect of an EPUB publication. These elements serve to centralize metadata, detail the individual resources, and provide the reading order and other information necessary for its rendering.

This library is primarily concerned with providing access to the metadata, manifest, and spine of the EPUB publication. Metadata refers to information about the publication, such as its title or authors. The manifest refers to the complete set of resources that are used to render the publication, such as XHTML documents and image files. And the spine refers to the ordered list of manifest items that represent the default reading order — the order that readers will encounter the manifest items by simply turning pages one at a time.

What this library does

@smoores/epub provides an API to interact with the metadata, manifest, and spine of the EPUB publication. There are higher level APIs that mostly abstract away the implementation details of the EPUB specification, like epub.setTitle(title: string) and epub.getCreators(), as well as lower level APIs like epub.writeItemContents(path: string, contents: Uint8Array) and epub.addMetadata(entry: MetadataEntry), which require some understanding of the EPUB structure to utilize effectively.

Because EPUB publications rely heavily on the XML document format, this library also provides utility methods for parsing, manipulating, and building XML documents. The underlying XML operations are based on fast-xml-parser.

Usage

The entrypoint to the library is through the Epub class. An Epub can either be read from an existing EPUB publication file, or created from scratch.

Reading from a file

import { Epub } from "@smoores/epub"

const epub = await Epub.from("path/to/book.epub")
console.log(await epub.getTitle())

Creating from scratch

When creating an Epub from scratch, the title, language, and identifier must be provided, as these are required for all publications by the EPUB 3 specification.

Other Dublin Core and non-core metadata may also be provided at creation time, or may be added incrementally after creation.

import { randomUUID } from "node:crypto"

import { Epub } from "@smoores/epub"

const epub = await Epub.create({
  title: "S'mores For Everyone",
  // This should be the primary language of the publication.
  // Individual content resources may specify their own languages.
  language: new Intl.Locale("en-US"),
  // This can be any unique identifier, including UUIDs, ISBNs, etc
  identifier: randomUUID(),
})

Adding a chapter

import { Epub, ManifestItem } from "@smoores/epub"

const epub = await Epub.from("path/to/book.epub")

// Construct a manifest item describing the chapter
const manifestItem: ManifestItem = {
  id: "chapter-one",
  // This is the filepath for the chapter contents within the
  // EPUB archive.
  href: "XHTML/chapter-one.xhtml",
  mediaType: "application/xhtml+xml",
}

// You can specify the contents as a string
const contents = `<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      xml:lang="en-US"
      lang="en-US">
  <head></head>
  <body>
    <h1>Chapter 1</h1>
    <p>At first, there were s'mores.</p>
  </body>
</html>`

// Or you can specify the contents as an XML structure
const xmlContents = epub.createXhtmlDocument([
  Epub.createXmlElement("h1", {}, [Epub.createXmlTextNode("Chapter 1")]),
  Epub.createXmlElement("p", {}, [
    Epub.createXmlTextNode("At first, there were s'mores."),
  ]),
])

// First, add the new item to the manifest, and add
// its contents to the publication
await epub.addManifestItem(manifestItem, contents, "utf-8")

// OR, using the XMl:
await epub.addManifestItem(manifestItem, xmlContents, "xml")

// Then add the item to the spine
await epub.addSpineItem(manifestItem.id)

Writing to disk

import { Epub } from "@smoores/epub"

const epub = await Epub.from("path/to/book.epub")
await epub.setTitle("S'mores for Everyone")

await epub.writeToFile("path/to/updated.epub")

Writing to a byte array

import { randomUUID } from "node:crypto"

import { Epub } from "@smoores/epub"

const epub = await Epub.create({
  title: "S'mores For Everyone",
  language: new Intl.Locale("en-US"),
  identifier: randomUUID(),
})

const data: Uint8Array = await epub.writeToArray()

For more details about using the API, see the API documentation.

Development

This package lives in the Storyteller monorepo, and is developed alongside the Storyteller platform.

To get started with developing in the Storyteller monorepo, check out the development guides in the docs.

API Docs

• Epub
  • Link
  • Properties
    • xhtmlBuilder
    • xhtmlParser
    • xmlBuilder
    • xmlParser
  • Methods
    • addContributor()
    • addCreator()
    • addManifestItem()
    • addMetadata()
    • addSpineItem()
    • addSubject()
    • close()
    • createXhtmlDocument()
    • getContributors()
    • getCoverImage()
    • getCoverImageItem()
    • getCreators()
    • getLanguage()
    • getManifest()
    • getMetadata()
    • getPackageVocabularyPrefixes()
    • getPublicationDate()
    • getSpineItems()
    • getSubjects()
    • getTitle()
    • getType()
    • readItemContents()
    • readXhtmlItemContents()
    • removeContributor()
    • removeCreator()
    • removeManifestItem()
    • removeSpineItem()
    • replaceMetadata()
    • setCoverImage()
    • setLanguage()
    • setPackageVocabularyPrefix()
    • setPublicationDate()
    • setTitle()
    • setType()
    • updateManifestItem()
    • writeItemContents()
    • writeToArray()
    • writeToFile()
    • writeXhtmlItemContents()
    • addLinkToXhtmlHead()
    • create()
    • createXmlElement()
    • createXmlTextNode()
    • findXmlChildByName()
    • formatSmilDuration()
    • from()
    • getXhtmlBody()
    • getXhtmlTextContent()
    • getXmlChildren()
    • getXmlElementName()
    • isXmlTextNode()
    • replaceXmlChildren()
• AlternateScript
  • Properties
    • locale
    • name
• DcCreator
  • Properties
    • alternateScripts?
    • fileAs?
    • name
    • role?
• DcSubject
  • Properties
    • authority
    • term
    • value
• DublinCore
  • Properties
    • contributors?
    • creators?
    • date?
    • identifier
    • language
    • subjects?
    • title
    • type?
• ElementName
  • Defined in
• EpubMetadata
  • Defined in
• ManifestItem
  • Type declaration
    • fallback?
    • href
    • id
    • mediaOverlay?
    • mediaType?
    • properties?
  • Defined in
• MetadataEntry
  • Type declaration
    • id?
    • properties
    • type
    • value
  • Defined in
• ParsedXml
  • Defined in
• XmlElement<Name>
  • Type declaration
    • :@?
  • Type Parameters
  • Defined in
• XmlNode
  • Defined in
• XmlTextNode
  • Type declaration
    • #text
  • Defined in

Epub

A single EPUB instance.

The entire EPUB contents will be read into memory.

Example usage:

import { Epub, getBody, findByName, textContent } from "@smoores/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/

Properties

xhtmlBuilder

static xhtmlBuilder: XMLBuilder

Defined in

index.ts:230

xhtmlParser

static xhtmlParser: XMLParser

Defined in

index.ts:198

xmlBuilder

static xmlBuilder: XMLBuilder

Defined in

index.ts:223

xmlParser

static xmlParser: XMLParser

Defined in

index.ts:191

Methods

addContributor()

addContributor(contributor, index?): 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').

Parameters

Parameter	Type
contributor	DcCreator
index?	number

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dccreator

Defined in

index.ts:1507

addCreator()

addCreator(creator, index?, type?): Promise<void>

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.

Parameters

Parameter	Type	Default value
creator	DcCreator	undefined
index?	number	undefined
type?	"creator" | "contributor"	"creator"

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dccreator

Defined in

index.ts:1346

addManifestItem()

Call Signature

addManifestItem(item, contents, encoding): Promise<void>

Create a new manifest item and write its contents to a new entry.

Parameters

Parameter	Type	Description
item	ManifestItem	-
contents	ParsedXml	The new contents. May be either a parsed XML tree or a unicode string, as determined by the as argument.
encoding	"xml"	Optional - whether to interpret contents as a parsed XML tree, a unicode string, or a byte array. Defaults to a byte array.

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-manifest

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1862

Call Signature

addManifestItem(item, contents, encoding): Promise<void>

Create a new manifest item and write its contents to a new entry.

Parameters

Parameter	Type	Description
item	ManifestItem	-
contents	string	The new contents. May be either a parsed XML tree or a unicode string, as determined by the as argument.
encoding	"utf-8"	Optional - whether to interpret contents as a parsed XML tree, a unicode string, or a byte array. Defaults to a byte array.

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-manifest

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1867

Call Signature

addManifestItem(item, contents): Promise<void>

Create a new manifest item and write its contents to a new entry.

Parameters

Parameter	Type	Description
item	ManifestItem	-
contents	Uint8Array<ArrayBufferLike>	The new contents. May be either a parsed XML tree or a unicode string, as determined by the as argument.

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-manifest

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1872

addMetadata()

addMetadata(entry): 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().

Parameters

Parameter	Type
entry	MetadataEntry

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-metadata

Defined in

index.ts:1995

addSpineItem()

addSpineItem(manifestId, index?): Promise<void>

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.

Parameters

Parameter	Type
manifestId	string
index?	number

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-spine-elem

Defined in

index.ts:1565

addSubject()

addSubject(subject): Promise<void>

Add a subject to the EPUB metadata.

Parameters

Parameter	Type	Description
subject	string | DcSubject	May be a string representing just a schema-less subject name, or a DcSubject object

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dcsubject

Defined in

index.ts:985

close()

close(): Promise<void>

Close the Epub. Must be called before the Epub goes out of scope/is garbage collected.

Returns

Promise<void>

Defined in

index.ts:418

createXhtmlDocument()

createXhtmlDocument(body, head?, language?): Promise<(XmlElement<"html"> | XmlElement<"?xml">)[]>

Create a new XHTML document with the given body and head.

Parameters

Parameter	Type	Description
body	ParsedXml	The XML nodes to place in the body of the document
head?	ParsedXml	Optional - the XMl nodes to place in the head
language?	Locale	Optional - defaults to the EPUB's language

Returns

Promise<(XmlElement<"html"> | XmlElement<"?xml">)[]>

Defined in

index.ts:1678

getContributors()

getContributors(): Promise<DcCreator[]>

Retrieve the list of contributors.

This is a convenience method for epub.getCreators('contributor').

Returns

Promise<DcCreator[]>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dccontributor

Defined in

index.ts:1333

getCoverImage()

getCoverImage(): Promise<null | Uint8Array<ArrayBufferLike>>

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().

Returns

Promise<null | Uint8Array<ArrayBufferLike>>

Link

https://www.w3.org/TR/epub-33/#sec-cover-image

Defined in

index.ts:888

getCoverImageItem()

getCoverImageItem(): Promise<null | ManifestItem>

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.

Returns

Promise<null | ManifestItem>

Link

https://www.w3.org/TR/epub-33/#sec-cover-image

Defined in

index.ts:869

getCreators()

getCreators(type): Promise<DcCreator[]>

Retrieve the list of creators.

Parameters

Parameter	Type	Default value
type	"creator" | "contributor"	"creator"

Returns

Promise<DcCreator[]>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dccreator

Defined in

index.ts:1275

getLanguage()

getLanguage(): Promise<null | Locale>

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.

Returns

Promise<null | Locale>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dclanguage

Defined in

index.ts:1069

getManifest()

getManifest(): Promise<Record<string, ManifestItem>>

Retrieve the manifest for the Epub.

This is represented as a map from each manifest items' id to the rest of its properties.

Returns

Promise<Record<string, ManifestItem>>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-manifest

Defined in

index.ts:664

getMetadata()

getMetadata(): Promise<EpubMetadata>

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().

Returns

Promise<EpubMetadata>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-metadata

Defined in

index.ts:791

getPackageVocabularyPrefixes()

getPackageVocabularyPrefixes(): Promise<Record<string, string>>

Return the set of custom vocabulary prefixes set on this publication's root package element.

Returns a map from prefix to URI

Returns

Promise<Record<string, string>>

Link

https://www.w3.org/TR/epub-33/#sec-prefix-attr

Defined in

index.ts:1181

getPublicationDate()

getPublicationDate(): Promise<null | Date>

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.

Returns

Promise<null | Date>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dcdate

Defined in

index.ts:925

getSpineItems()

getSpineItems(): Promise<ManifestItem[]>

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.

Returns

Promise<ManifestItem[]>

Link

https://www.w3.org/TR/epub-33/#sec-spine-elem

Defined in

index.ts:1546

getSubjects()

getSubjects(): Promise<(string | DcSubject)[]>

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.

Returns

Promise<(string | DcSubject)[]>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dcsubject

Defined in

index.ts:1024

getTitle()

getTitle(short): Promise<undefined | string>

Retrieve the title of the Epub.

Parameters

Parameter	Type	Default value	Description
short	boolean	false	Optional - whether to return only the first title segment if multiple are found. Otherwise, will follow the spec to combine title segments

Returns

Promise<undefined | string>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dctitle

Defined in

index.ts:1111

getType()

getType(): Promise<null | MetadataEntry>

Retrieve the publication type from the dc:type element in the EPUB metadata.

If there is no dc:type element, returns null.

Returns

Promise<null | MetadataEntry>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dctype

Defined in

index.ts:972

readItemContents()

Call Signature

readItemContents(id): Promise<Uint8Array<ArrayBufferLike>>

Retrieve the contents of a manifest item, given its id.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to retrieve

Returns

Promise<Uint8Array<ArrayBufferLike>>

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1650

Call Signature

readItemContents(id, encoding): Promise<string>

Retrieve the contents of a manifest item, given its id.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to retrieve
encoding	"utf-8"	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.

Returns

Promise<string>

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1651

readXhtmlItemContents()

Call Signature

readXhtmlItemContents(id, as?): Promise<ParsedXml>

Retrieves the contents of an XHTML item, given its manifest id.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to retrieve
as?	"xhtml"	Optional - whether to return the parsed XML document tree, or the concatenated text of the document. Defaults to the parsed XML tree.

Returns

Promise<ParsedXml>

Link

https://www.w3.org/TR/epub-33/#sec-xhtml

Defined in

index.ts:1711

Call Signature

readXhtmlItemContents(id, as): Promise<string>

Retrieves the contents of an XHTML item, given its manifest id.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to retrieve
as	"text"	Optional - whether to return the parsed XML document tree, or the concatenated text of the document. Defaults to the parsed XML tree.

Returns

Promise<string>

Link

https://www.w3.org/TR/epub-33/#sec-xhtml

Defined in

index.ts:1712

removeContributor()

removeContributor(index): 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').

Parameters

Parameter	Type
index	number

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dccreator

Defined in

index.ts:1491

removeCreator()

removeCreator(index, type): 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().

Parameters

Parameter	Type	Default value
index	number	undefined
type	"creator" | "contributor"	"creator"

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dccreator

Defined in

index.ts:1435

removeManifestItem()

removeManifestItem(id): Promise<void>

Parameters

Parameter	Type
id	string

Returns

Promise<void>

Defined in

index.ts:1812

removeSpineItem()

removeSpineItem(index): Promise<void>

Remove the spine item at the specified index.

Parameters

Parameter	Type
index	number

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-spine-elem

Defined in

index.ts:1605

replaceMetadata()

replaceMetadata(predicate, entry): 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.

Parameters

Parameter	Type	Description
predicate	(entry) => boolean	Calls predicate once for each metadata entry, until it finds one where predicate returns true
entry	MetadataEntry	The new entry to replace the found entry with

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-metadata

Defined in

index.ts:2040

setCoverImage()

setCoverImage(href, data): Promise<void>

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.

Parameters

Parameter	Type
href	string
data	Uint8Array<ArrayBufferLike>

Returns

Promise<void>

Defined in

index.ts:902

setLanguage()

setLanguage(locale): Promise<void>

Update the Epub's language metadata entry.

Updates the existing dc:language element if one exists. Otherwise creates a new element

Parameters

Parameter	Type
locale	Locale

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dclanguage

Defined in

index.ts:1094

setPackageVocabularyPrefix()

setPackageVocabularyPrefix(prefix, uri): Promise<void>

Set a custom vocabulary prefix on the root package element.

Parameters

Parameter	Type
prefix	string
uri	string

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-prefix-attr

Defined in

index.ts:1205

setPublicationDate()

setPublicationDate(date): Promise<void>

Set the dc:date metadata element with the provided date.

Updates the existing dc:date element if one exists. Otherwise creates a new element

Parameters

Parameter	Type
date	Date

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dcdate

Defined in

index.ts:940

setTitle()

setTitle(title): Promise<void>

Set the title of the Epub.

If a title already exists, only the first title metadata entry will be modified to match the new value.

If no title currently exists, a single title metadata entry will be created.

Parameters

Parameter	Type
title	string

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dctitle

Defined in

index.ts:1236

setType()

setType(type): Promise<void>

Set the dc:type metadata element.

Updates the existing dc:type element if one exists. Otherwise creates a new element.

Parameters

Parameter	Type
type	string

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-opf-dctype

Defined in

index.ts:956

updateManifestItem()

updateManifestItem(id, newItem): Promise<void>

Update the manifest entry for an existing item.

To update the contents of an entry, use epub.writeItemContents() or epub.writeXhtmlItemContents()

Parameters

Parameter	Type
id	string
newItem	Omit<ManifestItem, "id">

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-pkg-manifest

Defined in

index.ts:1939

writeItemContents()

Call Signature

writeItemContents(id, contents): Promise<void>

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.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to write new contents for
contents	Uint8Array<ArrayBufferLike>	The new contents. May be either a utf-8 encoded string or a byte array, as determined by the encoding

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1764

Call Signature

writeItemContents(id, contents, encoding): Promise<void>

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.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to write new contents for
contents	string	The new contents. May be either a utf-8 encoded string or a byte array, as determined by the encoding
encoding	"utf-8"	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.

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-contentdocs

Defined in

index.ts:1765

writeToArray()

writeToArray(): Promise<Uint8Array<ArrayBufferLike>>

Write the current contents of the Epub to a new Uint8Array.

This does not close the Epub. It can continue to be modified after it has been written to disk. Use epub.close() to close the Epub.

When this method is called, the "dcterms:modified" meta tag is automatically updated to the current UTC timestamp.

Returns

Promise<Uint8Array<ArrayBufferLike>>

Defined in

index.ts:2091

writeToFile()

writeToFile(path): Promise<void>

Write the current contents of the Epub to a new EPUB archive on disk.

This does not close the Epub. It can continue to be modified after it has been written to disk. Use epub.close() to close the Epub.

When this method is called, the "dcterms:modified" meta tag is automatically updated to the current UTC timestamp.

Parameters

Parameter	Type	Description
path	string	The file path to write the new archive to. The parent directory does not need te exist -- the path will be recursively created.

Returns

Promise<void>

Defined in

index.ts:2148

writeXhtmlItemContents()

writeXhtmlItemContents(id, contents): 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.

Parameters

Parameter	Type	Description
id	string	The id of the manifest item to write new contents for
contents	ParsedXml	The new contents. Must be a parsed XML tree.

Returns

Promise<void>

Link

https://www.w3.org/TR/epub-33/#sec-xhtml

Defined in

index.ts:1804

addLinkToXhtmlHead()

static addLinkToXhtmlHead(xml, link): void

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.

Parameters

Parameter	Type
xml	ParsedXml
link	{ href: string; rel: string; type: string; }
link.href	string
link.rel	string
link.type	string

Returns

void

Defined in

index.ts:260

create()

static create(dublinCore, additionalMetadata): Promise<Epub>

Construct an Epub instance, optionally beginning with the provided metadata.

Parameters

Parameter	Type	Default value	Description
dublinCore	DublinCore	undefined	Core metadata terms
additionalMetadata	EpubMetadata	[]	An array of additional metadata entries

Returns

Promise<Epub>

Defined in

index.ts:434

createXmlElement()

static createXmlElement<Name>(name, properties, children): XmlElement<Name>

Type Parameters

Type Parameter

Name extends `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}`

Parameters

Parameter	Type	Default value
name	Name	undefined
properties	Record<string, string>	undefined
children	XmlNode[]	[]

Returns

XmlElement<Name>

Defined in

index.ts:295

createXmlTextNode()

static createXmlTextNode(text): XmlTextNode

Parameters

Parameter	Type
text	string

Returns

XmlTextNode

Defined in

index.ts:308

findXmlChildByName()

static findXmlChildByName<Name>(name, xml, filter?): undefined | XmlElement<Name>

Given an XML structure, find the first child matching the provided name and optional filter.

Type Parameters

Type Parameter

Name extends `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}`

Parameters

Parameter	Type
name	Name
xml	ParsedXml
filter?	(node) => boolean

Returns

undefined | XmlElement<Name>

Defined in

index.ts:369

formatSmilDuration()

static formatSmilDuration(duration): string

Format a duration, provided as a number of seconds, as a SMIL clock value, to be used for Media Overlays.

Parameters

Parameter	Type
duration	number

Returns

string

Link

https://www.w3.org/TR/epub-33/#sec-duration

Defined in

index.ts:243

from()

static from(path): Promise<Epub>

Construct an Epub instance by reading an EPUB file from path.

Parameters

Parameter	Type	Description
path	string	Must be a valid filepath to an EPUB archive

Returns

Promise<Epub>

Defined in

index.ts:513

getXhtmlBody()

static getXhtmlBody(xml): ParsedXml

Given an XML structure representing a complete XHTML document, return the sub-structure representing the children of the document's body element.

Parameters

Parameter	Type
xml	ParsedXml

Returns

ParsedXml

Defined in

index.ts:285

getXhtmlTextContent()

static getXhtmlTextContent(xml): string

Given an XML structure representing a complete XHTML document, return a string representing the concatenation of all text nodes in the document.

Parameters

Parameter	Type
xml	ParsedXml

Returns

string

Defined in

index.ts:317

getXmlChildren()

static getXmlChildren<Name>(element): ParsedXml

Given an XMLElement, return a list of its children

Type Parameters

Type Parameter

Name extends `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}`

Parameters

Parameter	Type
element	XmlElement<Name>

Returns

ParsedXml

Defined in

index.ts:349

getXmlElementName()

static getXmlElementName<Name>(element): Name

Given an XMLElement, return its tag name.

Type Parameters

Type Parameter

Name extends `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}`

Parameters

Parameter	Type
element	XmlElement<Name>

Returns

Name

Defined in

index.ts:334

isXmlTextNode()

static isXmlTextNode(node): node is XmlTextNode

Given an XMLNode, determine whether it represents a text node or an XML element.

Parameters

Parameter	Type
node	XmlNode

Returns

node is XmlTextNode

Defined in

index.ts:382

replaceXmlChildren()

static replaceXmlChildren<Name>(element, children): void

Type Parameters

Type Parameter

Name extends `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}`

Parameters

Parameter	Type
element	XmlElement<Name>
children	XmlNode[]

Returns

void

Defined in

index.ts:357

---

AlternateScript

Properties

locale

locale: Locale

Defined in

index.ts:142

name

name: string

Defined in

index.ts:141

---

DcCreator

Properties

alternateScripts?

optional alternateScripts: AlternateScript[]

Defined in

index.ts:149

fileAs?

optional fileAs: string

Defined in

index.ts:148

name

name: string

Defined in

index.ts:146

role?

optional role: string

Defined in

index.ts:147

---

DcSubject

Properties

authority

authority: string

Defined in

index.ts:136

term

term: string

Defined in

index.ts:137

value

value: string

Defined in

index.ts:135

---

DublinCore

Properties

contributors?

optional contributors: DcCreator[]

Defined in

index.ts:159

creators?

optional creators: DcCreator[]

Defined in

index.ts:158

date?

optional date: Date

Defined in

index.ts:156

identifier

identifier: string

Defined in

index.ts:155

language

language: Locale

Defined in

index.ts:154

subjects?

optional subjects: (string | DcSubject)[]

Defined in

index.ts:157

title

title: string

Defined in

index.ts:153

type?

optional type: string

Defined in

index.ts:160

---

ElementName

ElementName: `${Letter | Uppercase<Letter> | QuestionMark}${string}`

A valid name for an XML element (must start with a letter)

Defined in

index.ts:63

---

EpubMetadata

EpubMetadata: MetadataEntry[]

Defined in

index.ts:132

---

ManifestItem

ManifestItem: object

Type declaration

fallback?

optional fallback: string

href

href: string

id

id: string

mediaOverlay?

optional mediaOverlay: string

mediaType?

optional mediaType: string

properties?

optional properties: string[]

Defined in

index.ts:82

---

MetadataEntry

MetadataEntry: object

Type declaration

id?

optional id: string

properties

properties: Record<string, string>

type

type: ElementName

value

value: string | undefined

Defined in

index.ts:125

---

ParsedXml

ParsedXml: XmlNode[]

An XML structure

Defined in

index.ts:80

---

XmlElement<Name>

XmlElement<Name>: object & { [key in Name]: ParsedXml }

An XML element

Type declaration

:@?

optional :@: Record<string, string>

Type Parameters

Type Parameter	Default type
Name extends ElementName	ElementName

Defined in

index.ts:67

---

XmlNode

XmlNode: XmlElement | XmlTextNode

A valid XML node. May be either an element or a text node.

Defined in

index.ts:77

---

XmlTextNode

XmlTextNode: object

A text node in an XML document

Type declaration

#text

#text: string

Defined in

index.ts:74