The parseEpub function returns an EpubObject containing the following main properties:

• structure: The parsed Table of Contents (toc) of the EPUB file, describing the book's construction.
• sections: An array of chapters or sections referenced in the structure. Each section object contains the raw HTML string and provides utility methods for conversion.
• info: Metadata about the EPUB.

Note: Properties starting with _ are private and subject to change; they should not be used directly.

You can install the package using either npm or yarn to add it to your project dependencies.

npm install @gxl/epub-parser --save

or

yarn add @gxl/epub-parser

Import parseEpub from @gxl/epub-parser to convert an EPUB file into a JavaScript object. The function is asynchronous and accepts a file path, binary string, or buffer as the target.

import { parseEpub } from '@gxl/epub-parser'

const epubObj = await parseEpub('/path/to/file.epub', {
  type: 'path',
})

console.log('epub content:', epubObj)

Each object in the sections array provides methods to transform the raw HTML content into other formats:

• Section.prototype.toMarkdown: Converts the section to a Markdown object.
• Section.prototype.toHtmlObjects: Converts the section to an HTML object.
  • Note on Links/Sources: While raw HTML src and href attributes remain untouched, toHtmlObjects resolves src to base64 strings and modifies href to internal references in the format #{sectionId},{hash} to ensure they work within the parsed context.

The parseEpub function is the primary entry point for the library.

Signature: parseEpub(target: string | buffer, options?: object): EpubObject

Parameters:

• target (string | buffer): The input data. This can be a file path, a file's binary string, or a buffer.
• options (object): Configuration options.
  • type (optional): 'binaryString' | 'path' | 'buffer'. Forces the parser to treat the target as the specified type. This is useful if the parser cannot automatically determine the input type.

The parserWrapper function accepts an optional options object of type ParserOptions:

• type: Specifies how to treat the target string.
  • 'binaryString': (Default) Treats the string as the raw content of the EPUB.
  • 'path': Treats the string as a filesystem path to the EPUB file.
• expand: A boolean that, when passed to the underlying parse method, controls how sections are resolved. If true, it triggers an expanded resolution of sections.

const options = {
  type: 'path' as const,
  expand: true
};

const epub = await parserWrapper('/path/to/book.epub', options);

The Epub class exposes a resolve(path: string) method to access files inside the EPUB container. It returns an object containing an asText() method to retrieve the file content as a string.

Paths starting with / are treated as absolute from the zip root. Otherwise, they are resolved relative to the EPUB's internal root.

// Assuming 'epub' is a parsed Epub instance
const file = epub.resolve('/META-INF/container.xml');
const content = file.asText();

The primary entry point for the library is the parserWrapper function. It accepts an EPUB file as either a file path (string) or a Buffer. It returns a promise that resolves to an Epub instance after parsing the content.

To ensure correct behavior when passing a string that might be mistaken for a binary string instead of a path, you can explicitly set the type option to 'path' in the ParserOptions object.

import parserWrapper from 'epub-parser';

// Using a file path
const epub = await parserWrapper('/path/to/book.epub', { type: 'path' });

// Using a Buffer
const buffer = fs.readFileSync('book.epub');
const epub = await parserWrapper(buffer);

console.log(epub.info.title);

The primary entry point for the library is the parseEpub function. It is used to parse an EPUB file provided as either a file path (string) or a Buffer. The function returns an EpubObject containing the parsed content of the EPUB.

import { parseEpub } from '@gxl/epub-parser';

// Using a file path
const epubData = await parseEpub('/path/to/book.epub');

// Using a Buffer
const epubDataFromBuffer = await parseEpub(buffer);

Once parsed, the Epub instance provides several properties to access the book's content:

• info: An object containing basic metadata: title, author, and publisher.
• structure: A hierarchical representation of the Table of Contents (TOC), containing name, sectionId, nodeId, path, playOrder, and children.
• sections: An array of Section objects parsed from the spine, representing the actual content of the book.

Note: The parse() method is asynchronous and must be awaited (either directly or via the parserWrapper convenience function) before these properties are populated.