epub2

epub2 is a Node.js/TypeScript library for parsing EPUB electronic book files, exposing an EPub class (extending EventEmitter) that unpacks the zip-based EPUB container, verifies its mimetype, and walks the container.xml -> OPF rootfile -> NCX table of contents to build metadata, manifest, spine, flow, and toc structures usable directly from application code. It is maintained as one package inside the bluelovers/ws-epub Lerna monorepo alongside companion tools like epub-extract, epub-maker2, and novel-epub, and describes itself as a fork of the long-unmaintained epub package with TypeScript types and modern packaging added on top.

Consumers get a getChapter/getImage/getFile callback API for pulling chapter text, embedded images, and arbitrary files out of the archive by manifest id, plus a createAsync/*Async Promise layer (built on bluebird) for use in async/await code without hand-rolling promisification. It only supports UTF-8-encoded EPUB content, and — like its upstream ancestor — has no runnable automated test suite in this snapshot, so correctness for a given book still needs to be validated manually against the target file.

What You Get

• EPub class parsing container.xml, OPF metadata/manifest/spine, and NCX TOC into ready-to-use JS objects
• getChapter/getChapterRaw/getImage/getFile callback methods for extracting content by manifest id
• createAsync plus getChapterAsync/getImageAsync/getFileAsync Promise wrappers built on bluebird
• Full TypeScript typings (index.d.ts, epub.d.ts) generated alongside the compiled JS
• A listImage() helper that filters the manifest down to image entries by MIME type and file extension

Common Use Cases

• Extracting chapter text and images from EPUB files to power an e-reader or preview UI
• Reading book metadata (title, author, language) for a personal library/cataloging tool
• Batch-converting or re-packaging EPUB content as part of a novel/manga scraping pipeline, alongside sibling packages in the same monorepo that target novel/comic workflows
• Validating that an uploaded file is a well-formed EPUB before accepting it in a content pipeline

Under The Hood

Architecture The EPub class (lib/epub.ts) extends EventEmitter; its constructor stores the filename and image/link URL roots, and .parse() resets internal state then calls .open(), which uses a custom ZipFile wrapper (zipfile.ts) to read the archive, checkMimeType() verifies “application/epub+zip”, and the parser walks container.xml to the OPF rootfile for metadata/manifest/spine, then the NCX for the table of contents, emitting “end” or “error” events. index.ts wraps this callback-based class in a subclass adding createAsync (a Promise-returning factory) and *_Async wrappers (getChapterAsync, getImageAsync, getFileAsync) built on bluebird’s Promise.fromCallback, plus a listImage() helper — a fairly flat wrapper-over-emitter design, so behavior changes to the underlying event-driven parse ripple directly into every async wrapper method.

Tech Stack Written in TypeScript with both .ts sources and their compiled .js/.d.ts output checked into the package; dependencies include adm-zip (via a custom zipfile.ts wrapper implementing an IZipFile interface), xml2js for container/OPF/NCX XML parsing, bluebird for Promise.fromCallback-based promisification, array-hyper-unique for de-duplicating arrays, crlf-normalize for line-ending handling, and tslib for TypeScript helpers. Built via a Lerna-managed Yarn monorepo (ws-epub) alongside sibling packages (epub-extract, epub-maker2, epub-util, novel-epub, and others); ships plain compiled CommonJS plus typings with no bundler, targeting Node.js consumers.

Code Quality A jest.config.js is present, but the test/ directory holds only example scripts (test/example/example.ts, example2.ts) and fixture .epub files rather than assertion-based test suites, and the package’s own “test” script is literally an echo of “no test specified” — so there is no real automated coverage in this snapshot despite jest being a devDependency. Error handling follows Node-style (err, data) callbacks plus EventEmitter “error” emission rather than typed Result patterns; naming is consistent camelCase, and TypeScript is used throughout, though a handful of // @ts-ignore escapes (e.g. accessing this.__proto__.constructor) undercut the type safety. No CI workflow file was found in the clone, and no ESLint/Prettier config scoped specifically to this package.

What Makes It Unique epub2 does not introduce a new parsing technique — it is explicitly framed in its own README as a fork of the older, unmaintained epub package, with TypeScript typings and a Promise-based async surface (createAsync, *Async methods) layered on via bluebird, plus small ergonomic additions like listImage() for filtering manifest entries down to images. That makes it a useful maintenance and developer-experience upgrade over the original rather than a novel architecture, and the core technique — event-driven zip/XML parsing — is the same one the original module used.