NB! Only ebooks in UTF-8 are currently supported!.
Usage
- Ready an instance of File or
Blob
containing the epub data then pass it to the followingepub
function or its variants.
import epub from '@jcsj/epub'
// Inside an async block
async function load() {
const epub = await epub(file);
//...
}
//Or with a promise
epub(file).then(epub => {
//...
})
//Use the 2nd arg to handle parser progress events
epub(file, {
metadata(metadata) {
console.log("Meta:", metadata);
//Set the tab's title with the book's title.
document.title = metadata.title;
},
manifest(manifest) {
console.log("Manifest: ", manifest);
},
spine(spine) {
console.log("Spine:", spine);
},
flow(flow) {
console.log("Flow: ", flow);
},
toc(toc) {
console.log("TOC: ", toc);
}
//Can also be async
async root() {
console.log("Root found!")
},
})
V2 Major Change
- Julien's version included mandatory sanitization checks. While I added memoization in my version for my use case. Since V2 is now implemented in a functional way, those features has been moved to other functions for extensibility
- MemoizedEpub.
- SanitizedEpub
- MemoizedAndSanitizedEpub - Combines both MemoizedEpub and the SanitizedEpub features
- The variants have
getContentRaw
, to call the original getcontent
import { MemoizedEpub, SanitizedEpub, MemoizedEpubAndSanitized } from "@jcsj/epub"
//Same usage as `epub`
MemoizedEpub(file,{
metadata(metadata) {
//...
}
}).then(memoizedEpub => {
//...
})
DEPRECATED:
async getFileInArchive(id)
async readFile(id, writer="text")
- data - string.
- the writer determines the data's string representation:
- "text" for chapter data in utf-8.
- "image" for base64 string of an image.
Use Reader.read instead
- These has been simplified into Reader.read,
- but was moved out of epub as I found it to be rarely used in that form.
const toc:LoadedEntry = await epub.parser.reader.read("toc")
console.log(toc.data)
Item
An object/interface that contains basic file info from the archive. It is the most important structure as the manifest, flow, toc uses or extends it. It has the following propperties:
- id - Unique id of the file. Most methods use this as a parameter.
- href - path of the file if it were in a filesystem.
- media-type - The type of the file.
manifest
Contains all the files of the epub archive as an object whose values implement Item.
epub.manifest
metadata
Property of the epub object that holds several metadata fields about the book.
epub.metadata
Available fields:
- creator Author of the book (if multiple authors, will be seperated with '|') (Lewis Carroll)
- title Title of the book (Alice's Adventures in Wonderland)
- date creation of the file (2006-08-12)
- language Language code (en or en-us etc.)
- subject? Topic of the book (Fantasy)
- description?
- UUID? UUID string
- ISBN? ISBN string
flow
An instance of Flow class which is a Map whose values implement Item. It's a slice of manifest. The values hold the actual list of chapters (TOC is just an indication and can link to a # url inside a chapter file).
epub.flow.forEach([key, value] => {
console.log(key, value)
})
Chapter id
is needed to load the chapters with getContent
toc
It is an instance of TableOfContents that extends Map whose values implement Chapter . It is basically a slice of Flow. It indicates a list of titles/urls for the TOC. Actual chapter(the file) is accessed with the href
property.
Chapter
An extension of Item with the following additional properties:
- order - int
- title - string
async getContent(chapterId)
Loads chapter text from the ebook as a promise.
let text = await epub.getContent('chapter1')
async getImage(imageId)
- Load's image as a base64 string from the ebook.
- This can be used as the src of an HTML img element.
- use MemoizedEpub for caching.
Usage
const coverImage = await epub.getImage('cover');
const imageElement = document.createElement("img")
imageElement.src = coverImage
document.body.appendChild(imageElement)
MemoizedEpub
async getImage(imageId)
async getContent(chapterId)
async getContentRaw(chapterId)
SanitizedEpub
async getContent(chapterId)
- Load raw chapter text from the ebook. It is altered to be web safe
- Keeps only the body tag.
- Removes scripts, styles, and event handlers
- Converts SVG IMG as a normal img tag.
- Replaces the original image.src with the embedded base64.
- Previous src is saved in dataset.src.
async getContentRaw(chapterId)
MemoizedAndSanitizedEpub
async getImage(imageId)
async getContent(chapterId)
async getContentRaw(chapterId)
Composability
- Create your custom implemention of epub by calling epub then overwriting and adding methods/properties to resulting epub interface. For examples, see the implementation of MemoizedEpub and its variants.
- For more fine grained control or writing your own parser, the functions used in epub most internally used functions are exported.
Julien-c's epub
Changes againstDependencies:
- adm-zip | zipfile -> @zip.js/zip.js
- xml2js -> xml-js -> @jcsj/xml-js (as of V2)
Implementation:
- Async-await based.
- Uses built-in
DOM
parsers instead ofregex
for getting content. - Flow and TOC are instances of Map instead of being just an Object.
- Use functions and TS interfaces instead of a class