A Node.js library for inspecting, modifying, and creating EPUB 3 publications.
npm:
npm install @smoores/epub
yarn:
yarn add @smoores/epub
deno:
deno install npm:@smoores/epub
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.
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.
@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.
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.
import { Epub } from "@smoores/epub"
const epub = await Epub.from("path/to/book.epub")
console.log(await epub.getTitle())
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(),
})
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)
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")
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.
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.
-
Epub
- Link
- Properties
-
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
- DcCreator
- DcSubject
- DublinCore
- ElementName
- EpubMetadata
- ManifestItem
- MetadataEntry
- ParsedXml
- XmlElement<Name>
- XmlNode
- XmlTextNode
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()
https://www.w3.org/TR/epub-33/
static
xhtmlBuilder:XMLBuilder
static
xhtmlParser:XMLParser
static
xmlBuilder:XMLBuilder
static
xmlParser:XMLParser
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')
.
Parameter | Type |
---|---|
contributor |
DcCreator |
index ? |
number |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dccreator
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.
Parameter | Type | Default value |
---|---|---|
creator |
DcCreator |
undefined |
index ? |
number |
undefined |
type ? |
"creator" | "contributor"
|
"creator" |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dccreator
addManifestItem(
item
,contents
,encoding
):Promise
<void
>
Create a new manifest item and write its contents to a new entry.
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. |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-pkg-manifest
https://www.w3.org/TR/epub-33/#sec-contentdocs
addManifestItem(
item
,contents
,encoding
):Promise
<void
>
Create a new manifest item and write its contents to a new entry.
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. |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-pkg-manifest
https://www.w3.org/TR/epub-33/#sec-contentdocs
addManifestItem(
item
,contents
):Promise
<void
>
Create a new manifest item and write its contents to a new entry.
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. |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-pkg-manifest
https://www.w3.org/TR/epub-33/#sec-contentdocs
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()
.
Parameter | Type |
---|---|
entry |
MetadataEntry |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-pkg-metadata
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.
Parameter | Type |
---|---|
manifestId |
string |
index ? |
number |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-spine-elem
addSubject(
subject
):Promise
<void
>
Add a subject to the EPUB metadata.
Parameter | Type | Description |
---|---|---|
subject |
string | DcSubject
|
May be a string representing just a schema-less subject name, or a DcSubject object |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
close():
Promise
<void
>
Close the Epub. Must be called before the Epub goes out of scope/is garbage collected.
Promise
<void
>
createXhtmlDocument(
body
,head
?,language
?):Promise
<(XmlElement
<"html"
> |XmlElement
<"?xml"
>)[]>
Create a new XHTML document with the given body and head.
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 |
Promise
<(XmlElement
<"html"
> |
XmlElement
<"?xml"
>)[]>
getContributors():
Promise
<DcCreator
[]>
Retrieve the list of contributors.
This is a convenience method for epub.getCreators('contributor')
.
Promise
<DcCreator
[]>
https://www.w3.org/TR/epub-33/#sec-opf-dccontributor
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().
Promise
<null
| Uint8Array
<ArrayBufferLike
>>
https://www.w3.org/TR/epub-33/#sec-cover-image
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.
Promise
<null
| ManifestItem
>
https://www.w3.org/TR/epub-33/#sec-cover-image
getCreators(
type
):Promise
<DcCreator
[]>
Retrieve the list of creators.
Parameter | Type | Default value |
---|---|---|
type |
"creator" | "contributor"
|
"creator" |
Promise
<DcCreator
[]>
https://www.w3.org/TR/epub-33/#sec-opf-dccreator
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.
Promise
<null
| Locale
>
https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
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.
Promise
<Record
<string
, ManifestItem
>>
https://www.w3.org/TR/epub-33/#sec-pkg-manifest
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()
.
Promise
<EpubMetadata
>
https://www.w3.org/TR/epub-33/#sec-pkg-metadata
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
Promise
<Record
<string
, string
>>
https://www.w3.org/TR/epub-33/#sec-prefix-attr
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.
Promise
<null
| Date
>
https://www.w3.org/TR/epub-33/#sec-opf-dcdate
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.
Promise
<ManifestItem
[]>
https://www.w3.org/TR/epub-33/#sec-spine-elem
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.
Promise
<(string
| DcSubject
)[]>
https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
getTitle(
short
):Promise
<undefined
|string
>
Retrieve the title of the Epub.
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 |
Promise
<undefined
| string
>
https://www.w3.org/TR/epub-33/#sec-opf-dctitle
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.
Promise
<null
| MetadataEntry
>
https://www.w3.org/TR/epub-33/#sec-opf-dctype
readItemContents(
id
):Promise
<Uint8Array
<ArrayBufferLike
>>
Retrieve the contents of a manifest item, given its id.
Parameter | Type | Description |
---|---|---|
id |
string |
The id of the manifest item to retrieve |
Promise
<Uint8Array
<ArrayBufferLike
>>
https://www.w3.org/TR/epub-33/#sec-contentdocs
readItemContents(
id
,encoding
):Promise
<string
>
Retrieve the contents of a manifest item, given its id.
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. |
Promise
<string
>
https://www.w3.org/TR/epub-33/#sec-contentdocs
readXhtmlItemContents(
id
,as
?):Promise
<ParsedXml
>
Retrieves the contents of an XHTML item, given its manifest id.
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. |
Promise
<ParsedXml
>
https://www.w3.org/TR/epub-33/#sec-xhtml
readXhtmlItemContents(
id
,as
):Promise
<string
>
Retrieves the contents of an XHTML item, given its manifest id.
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. |
Promise
<string
>
https://www.w3.org/TR/epub-33/#sec-xhtml
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')
.
Parameter | Type |
---|---|
index |
number |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dccreator
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()
.
Parameter | Type | Default value |
---|---|---|
index |
number |
undefined |
type |
"creator" | "contributor"
|
"creator" |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dccreator
removeManifestItem(
id
):Promise
<void
>
Parameter | Type |
---|---|
id |
string |
Promise
<void
>
removeSpineItem(
index
):Promise
<void
>
Remove the spine item at the specified index.
Parameter | Type |
---|---|
index |
number |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-spine-elem
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.
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 |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-pkg-metadata
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.
Parameter | Type |
---|---|
href |
string |
data |
Uint8Array <ArrayBufferLike > |
Promise
<void
>
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
Parameter | Type |
---|---|
locale |
Locale |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
setPackageVocabularyPrefix(
prefix
,uri
):Promise
<void
>
Set a custom vocabulary prefix on the root package element.
Parameter | Type |
---|---|
prefix |
string |
uri |
string |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-prefix-attr
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
Parameter | Type |
---|---|
date |
Date |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dcdate
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.
Parameter | Type |
---|---|
title |
string |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dctitle
setType(
type
):Promise
<void
>
Set the dc:type metadata element.
Updates the existing dc:type element if one exists. Otherwise creates a new element.
Parameter | Type |
---|---|
type |
string |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-opf-dctype
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()
Parameter | Type |
---|---|
id |
string |
newItem |
Omit <ManifestItem , "id" > |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-pkg-manifest
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.
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 |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-contentdocs
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.
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. |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-contentdocs
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.
Promise
<Uint8Array
<ArrayBufferLike
>>
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.
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. |
Promise
<void
>
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.
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. |
Promise
<void
>
https://www.w3.org/TR/epub-33/#sec-xhtml
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.
Parameter | Type |
---|---|
xml |
ParsedXml |
link |
{ href : string ; rel : string ; type : string ; } |
link.href |
string |
link.rel |
string |
link.type |
string |
void
static
create(dublinCore
,additionalMetadata
):Promise
<Epub
>
Construct an Epub instance, optionally beginning with the provided metadata.
Parameter | Type | Default value | Description |
---|---|---|---|
dublinCore |
DublinCore |
undefined |
Core metadata terms |
additionalMetadata |
EpubMetadata |
[] |
An array of additional metadata entries |
Promise
<Epub
>
static
createXmlElement<Name
>(name
,properties
,children
):XmlElement
<Name
>
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}` |
Parameter | Type | Default value |
---|---|---|
name |
Name |
undefined |
properties |
Record <string , string > |
undefined |
children |
XmlNode [] |
[] |
XmlElement
<Name
>
static
createXmlTextNode(text
):XmlTextNode
Parameter | Type |
---|---|
text |
string |
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 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}` |
Parameter | Type |
---|---|
name |
Name |
xml |
ParsedXml |
filter ? |
(node ) => boolean
|
undefined
| XmlElement
<Name
>
static
formatSmilDuration(duration
):string
Format a duration, provided as a number of seconds, as a SMIL clock value, to be used for Media Overlays.
Parameter | Type |
---|---|
duration |
number |
string
https://www.w3.org/TR/epub-33/#sec-duration
static
from(path
):Promise
<Epub
>
Construct an Epub instance by reading an EPUB file from path
.
Parameter | Type | Description |
---|---|---|
path |
string |
Must be a valid filepath to an EPUB archive |
Promise
<Epub
>
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.
Parameter | Type |
---|---|
xml |
ParsedXml |
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.
Parameter | Type |
---|---|
xml |
ParsedXml |
string
static
getXmlChildren<Name
>(element
):ParsedXml
Given an XMLElement, return a list of its children
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}` |
Parameter | Type |
---|---|
element |
XmlElement <Name > |
static
getXmlElementName<Name
>(element
):Name
Given an XMLElement, return its tag name.
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}` |
Parameter | Type |
---|---|
element |
XmlElement <Name > |
Name
static
isXmlTextNode(node
):node is XmlTextNode
Given an XMLNode, determine whether it represents a text node or an XML element.
Parameter | Type |
---|---|
node |
XmlNode |
node is XmlTextNode
static
replaceXmlChildren<Name
>(element
,children
):void
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}` |
Parameter | Type |
---|---|
element |
XmlElement <Name > |
children |
XmlNode [] |
void
locale:
Locale
name:
string
optional
alternateScripts:AlternateScript
[]
optional
fileAs:string
name:
string
optional
role:string
authority:
string
term:
string
value:
string
optional
contributors:DcCreator
[]
optional
creators:DcCreator
[]
optional
date:Date
identifier:
string
language:
Locale
optional
subjects: (string
|DcSubject
)[]
title:
string
optional
type:string
ElementName: `${Letter | Uppercase<Letter> | QuestionMark}${string}`
A valid name for an XML element (must start with a letter)
EpubMetadata:
MetadataEntry
[]
ManifestItem:
object
optional
fallback:string
href:
string
id:
string
optional
mediaOverlay:string
optional
mediaType:string
optional
properties:string
[]
MetadataEntry:
object
optional
id:string
properties:
Record
<string
,string
>
type:
ElementName
value:
string
|undefined
ParsedXml:
XmlNode
[]
An XML structure
XmlElement<
Name
>:object
&{ [key in Name]: ParsedXml }
An XML element
optional
:@:Record
<string
,string
>
Type Parameter | Default type |
---|---|
Name extends ElementName
|
ElementName |
XmlNode:
XmlElement
|XmlTextNode
A valid XML node. May be either an element or a text node.
XmlTextNode:
object
A text node in an XML document
#text:
string