Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including @ridi/epub-parser with all npm packages installed. Try it out:

var epubParser = require("@ridi/epub-parser")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@ridi/epub-parser v0.6.4

Common EPUB2 data parser for Ridibooks services

@ridi/epub-parser

Common EPUB2 data parser for Ridibooks services

NPM version Build Status codecov NPM total downloads

Features

  • [x] EPUB2 parsing
  • [ ] EPUB3 parsing
  • [x] Package validation with option
  • [x] Unzip epub file when parsing with options
  • [x] Read files
    • [x] Extract inner HTML of body in Spine with option
    • [x] Change base path of Spine, CSS and Inline style with option
    • [x] Customize CSS, Inline Style with options
    • [ ] Truncate inner HTML of body in Spine with options
    • [ ] Minify HTML, CSS, Inline Style with options
  • [x] Encrypt and decrypt function when parsing or reading or unzipping
  • [ ] More spec
    • [ ] encryption.xml
    • [ ] manifest.xml
    • [ ] metadata.xml
    • [ ] rights.xml
    • [ ] signatures.xml
  • [ ] Debug mode
  • [ ] Environment
    • [x] Node
    • [ ] CLI
    • [ ] Browser
  • [ ] Online demo

Install

npm install @ridi/epub-parser

Usage

Basic:

import { EpubParser } from '@ridi/epub-parser';
// or const { EpubParser } = require('@ridi/epub-parser');

const parser = new EpubParser('./foo/bar.epub' or './unzippedPath');
parser.parse(/* { parseOptions } */).then((book) => {
  parser.readItems(book.spines/*, { readOptions } */).then((results) => {
    ...
  });
  ...
});

with AesCryptor:

import { CryptoProvider, AesCryptor } from '@ridi/epub-parser';
// or const { CryptoProvider, AesCryptor } = require('@ridi/epub-parser');

const { Purpose } = CryptoProvider;
const { Mode, Padding } = AesCryptor;

class ContentCryptoProvider extends CryptoProvider {
  constructor(key) {
    super();
    this.cryptor = new AesCryptor(Mode.ECB, { key });
  }

  getCryptor(filePath, purpose) {
    return this.cryptor;
  }

  // If use as follows:
  // const provider = new ContentCryptoProvider(...);
  // const parser = new EpubParser('encrypted.epub', provider);
  // const book = await parser.parse({ unzipPath: ... });
  // const firstSpine = await parser.readItem(book.spines[0]);
  //
  // It will be called as follows:
  // 1. run(data, 'encrypted.epub', Purpose.READ_IN_DIR)
  // 2. run(data, 'META-INF/container.xml', Purpose.READ_IN_ZIP)
  // 3. run(data, 'OEBPS/content.opf', Purpose.READ_IN_ZIP)
  // ...
  // 4. run(data, 'mimetype', Purpose.WRITE)
  // ...
  // 5. run(data, 'OEBPS/Text/Section0001.xhtml', Purpose.READ_IN_DIR)
  //
  run(data, filePath, purpose) {
    const cryptor = this.getAesCryptor(filePath, purpose);
    const padding = Padding.AUTO;
    if (purpose === Purpose.READ_IN_DIR) {
      return cryptor.decrypt(data, { padding });
    } else if (purpose === Purpose.WRITE) {
      return cryptor.encrypt(data, { padding });
    }
    return data;
  }
}

const cryptoProvider = new ContentCryptoProvider(key);
const parser = new EpubParser('./encrypted.epub' or './unzippedPath', cryptoProvider);

Log level setting:

import { LogLevel, ... } from '@ridi/epub-parser';
const parser = new EpubParser(/* path */, /* cryptoProvider */, /* logLevel */)
// or const parser = new EpubParser(/* path */, /* logLevel */)
parser.logger.logLevel = LogLevel.VERBOSE; // SILENT, ERROR, WARN(default), INFO, DEBUG, VERBOSE

API

parse(parseOptions)

Returns Promise<EpubBook> with:

  • EpubBook: Instance with metadata, spine list, table of contents, etc.

Or throw exception.

parseOptions: ?object


readItem(item, readOptions)

Returns string or Buffer in Promise with:

or throw exception.

item: Item (see: Item Types)

readOptions: ?object


readItems(items, readOptions)

Returns string[] or Buffer[] in Promise with:

or throw exception.

items: Item[] (see: Item Types)

readOptions: ?object


unzip(unzipPath, overwrite)

Returns Promise<boolean> with:

  • If result is true, unzip is successful or has already been unzipped.

Or throw exception.

unzipPath: string

overwrite: boolean


onProgress = callback(step, totalStep, action)

Tells the progress of parser through callback.

const { Action } = EpubParser; // PARSE, READ_ITEMS
parser.onProgress = (step, totalStep, action) => {
  console.log(`[${action}] ${step} / ${totalStep}`);
}

Model

EpubBook

Author

  • name: ?string
  • fileAs: ?string
  • role: string (Default: Author.Roles.UNDEFINED)
  • toRaw(): object

Author.Roles

TypeValue
UNDEFINEDundefined
UNKNOWNunknown
ADAPTERadp
ANNOTATORann
ARRANGERarr
ARTISTart
ASSOCIATEDNAMEasn
AUTHORaut
AUTHOR_IN_QUOTATIONS_OR_TEXT_EXTRACTSaqt
AUTHOR_OF_AFTER_WORD_OR_COLOPHON_OR_ETCaft
AUTHOR_OF_INTRODUCTIONOR_ETCaui
BIBLIOGRAPHIC_ANTECEDENTant
BOOK_PRODUCERbkp
COLLABORATORclb
COMMENTATORcmm
DESIGNERdsr
EDITORedt
ILLUSTRATORill
LYRICISTlyr
METADATA_CONTACTmdc
MUSICIANmus
NARRATORnrt
OTHERoth
PHOTOGRAPHERpht
PRINTERprt
REDACTORred
REVIEWERrev
SPONSORspn
THESIS_ADVISORths
TRANSCRIBERtrc
TRANSLATORtrl

DateTime

  • value: ?string
  • event: string (Default: DateTime.Events.UNDEFINED)
  • toRaw(): object

DateTime.Events

TypeValue
UNDEFINEDundefined
UNKNOWNunknown
CREATIONcreation
MODIFICATIONmodification
PUBLICATIONpublication

Identifier

  • value: ?string
  • scheme: string (Default: Identifier.Schemes.UNDEFINED)
  • toRaw(): object

Identifier.Schemes

TypeValue
UNDEFINEDundefined
UNKNOWNunknown
DOIdoi
ISBNisbn
ISBN13isbn13
ISBN10isbn10
ISSNissn
UUIDuuid
URIuri

Meta

  • name: ?string
  • content: ?string
  • toRaw(): object

Guide

  • title: ?string
  • type: string (Default: Guide.Types.UNDEFINED)
  • href: ?string
  • item: ?Item
  • toRaw(): object

Guide.Types

TypeValue
UNDEFINEDundefined
UNKNOWNunknown
COVERcover
TITLE_PAGEtitle-page
TOCtoc
INDEXindex
GLOSSARYglossary
ACKNOWLEDGEMENTSacknowledgements
BIBLIOGRAPHYbibliography
COLOPHONcolophon
COPYRIGHT_PAGEcopyright-page
DEDICATIONdedication
EPIGRAPHepigraph
FOREWORDforeword
LOIloi
LOTlot
NOTESnotes
PREFACEpreface
TEXTtext

Item Types

Item

  • id: ?string
  • href: ?string
  • mediaType: ?string
  • size: ?number
  • isFileExists: boolean (size !== undefined)
  • toRaw(): object

SpineItem (extend Item)

NcxItem (extend Item)

CssItem (extend Item)

  • namespace: string

InlineCssItem (extend CssItem)

  • style: string (Default: '')

ImageItem (extend Item)

  • isCover: boolean (Default: false)

SvgItem (extend ImageItem)

FontItem (extend Item)

DeadItem (extend Item)

  • reason: string (Default: DeadItem.Reason.UNDEFINED)

DeadItem.Reason

TypeValue
UNDEFINEDundefined
UNKNOWNunknown
NOT_EXISTSnot_exists
NOT_SPINEnot_spine
NOT_NCXnot_ncx
NOT_SUPPORT_TYPEnot_support_type

NavPoint

  • id: ?string
  • label: ?string
  • src: ?string
  • anchor: ?string
  • depth: number (Default: 0)
  • children: NavPoint[]
  • spine: ?SpineItem
  • toRaw(): object

Version

  • major: number
  • minor: number
  • patch: number
  • toString(): string

Parse Options


validatePackage: boolean

If true, validation package specifications in IDPF listed below.

used only if input is EPUB file.

  • Zip header should not corrupt.
  • mimetype file must be first file in archive.
  • mimetype file should not compressed.
  • mimetype file should only contain string application/epub+zip.
  • Should not use extra field feature of ZIP format for mimetype file.

Default: false


allowNcxFileMissing: boolean

If false, stop parsing when NCX file not exists.

Default: true


unzipPath: ?string

If specified, unzip to that path.

only using if input is EPUB file.

Default: undefined


overwrite: boolean

If true, overwrite to unzipPath when unzip.

only using if unzipPath specified.

Default: true


parseStyle: boolean

If true, styles used for spine is described, and one namespace is given per CSS file or inline style.

Otherwise it CssItem.namespace, SpineItem.styles is undefined.

In any list, InlineCssItem is always positioned after CssItem. (EpubBook.styles, EpubBook.items, SpineItem.styles, ...)

Default: true


styleNamespacePrefix: string

Prepend given string to namespace for identification.

only available if parseStyle is true.

Default: 'ridi_style'


additionalInlineStyle: ?string

If specified, added inline styles to all spines.

only available if parseStyle is true.

Default: undefined

Read Options


force: boolean

If true, ignore any exceptions that occur within parser.

Default: false


basePath: ?string

If specified, change base path of paths used by spine and css.

HTML: SpineItem

...
  <!-- Before -->
  <div>
    <img src="../Images/cover.jpg">
  </div>
  <!-- After -->
  <div>
    <img src="{basePath}/OEBPS/Images/cover.jpg">
  </div>
...

CSS: CssItem, InlineCssItem

/* Before */
@font-face {
  font-family: NotoSansRegular;
  src: url("../Fonts/NotoSans-Regular.ttf");
}
/* After */
@font-face {
  font-family: NotoSansRegular;
  src: url("{basePath}/OEBPS/Fonts/NotoSans-Regular.ttf");
}

Default: undefined


extractBody: boolean|function

If true, extract body. Otherwise it returns a full string. If specify a function instead of true, use function to transform body.

false:

'<!doctype><html>\n<head>\n</head>\n<body style="background-color: #000000;">\n  <p>Extract style</p>\n  <img src=\"../Images/api-map.jpg\"/>\n</body>\n</html>'

true:

'<body style="background-color: #000000;">\n  <p>Extract style</p>\n  <img src=\"../Images/api-map.jpg\"/>\n</body>'

function:

readOptions.extractBody = (innerHTML, attrs) => {
  const string = attrs.map((attr) => {
    return ` ${attr.key}=\"${attr.value}\"`;
  }).join(' ');
  return `<article ${string}>${innerHTML}</article>`;
};
'<article style="background-color: #000000;">\n  <p>Extract style</p>\n  <img src=\"../Images/api-map.jpg\"/>\n</article>'

Default: false


serializedAnchor: Boolean

If true, replace file path of anchor in spine with spine index.

...
<spine toc="ncx">
  <itemref idref="Section0001.xhtml"/> <!-- index: 0 -->
  <itemref idref="Section0002.xhtml"/> <!-- index: 1 -->
  <itemref idref="Section0003.xhtml"/> <!-- index: 2 -->
  ...
</spine>
...
<!-- Before -->
<a href="./Text/Section0002.xhtml#title">Chapter 2</a>
<!-- After -->
<a href="1#title">Chapter 2</a>

Default: false


ignoreScript: boolean

Ignore all scripts from within HTML.

Default: false


removeAtrules: string[]

Remove at-rules.

Default: []


removeTagSelector: string[]

Remove selector that point to specified tags.

Default: []


removeIdSelector: string[]

Remove selector that point to specified ids.

Default: []


removeClassSelector: string[]

Remove selector that point to specified classes.

Default: []

License

MIT

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free