dyslibria-converter

The package ships a Node.js API together with a small CLI. Install it into any Node 20+ project that needs EPUB inspection or Dyslibria conversion without the rest of the application stack.

npm install dyslibria-converter

If you do not provide a preset or custom profile, the converter falls back to Dyslibria Default. By default it also returns an in-memory `outputBuffer` as well as the inspection and stats object. If you only want a file written to disk, pass `returnBuffer: false` to skip holding the output in memory.

import { convertBook } from 'dyslibria-converter';

const result = await convertBook('./books/input.epub', {
  outputPath: './books/input.dyslibria.epub',
  presetId: 'intense-scaffolding',
});

console.log(result.outputPath);
console.log(result.stats.processedFiles);
console.log(result.inspection.title);

• `inspection`: title, author, warnings, HTML entry list, and cover metadata
• `stats`: processed file count, skipped file count, duration, input bytes, and output bytes
• `outputPath`: present when you provide `outputPath`
• `outputBuffer`: present by default unless `returnBuffer` is set to `false`

The converter API accepts more than a plain file path. You can pass a string path, a `Buffer`, a `Uint8Array`, a readable stream, or an object wrapper containing a path, buffer, or stream with an optional filename.

That flexibility makes it easy to use in web workers, message consumers, or custom upload flows where the EPUB is already in memory.

import fs from 'node:fs';
import { convertBook } from 'dyslibria-converter';

const bufferResult = await convertBook({
  buffer: await fs.promises.readFile('./books/source.epub'),
  filename: 'source.epub',
});

const streamResult = await convertBook({
  stream: fs.createReadStream('./books/source.epub'),
  filename: 'source.epub',
}, {
  outputPath: './books/source.dyslibria.epub',
  returnBuffer: false,
});

• `outputPath`: copy the finished EPUB to a stable path you choose
• `returnBuffer`: keep or skip the in-memory output buffer
• `presetId`: select a built-in preset such as `intense-scaffolding` (Dyslibria Default) or `dyslibria-balanced`
• `profile` or `profilePath`: pass a full custom profile JSON or a reader-configuration export from the typography lab
• `deterministic`: keep reproducible output packaging enabled
• `dictionary` or `dictionaryPath`: override the word list used by the transform
• `tempRootDir`: choose where temporary workspaces are created
• `maxArchiveEntries` and `maxExtractBytes`: adjust archive-safety limits

If you prefer to hide the static functions behind a reusable object, `createConverter()` exposes the same conversion capability through an instance-style interface. That can be convenient in dependency-injected services or background worker classes.

import { createConverter } from 'dyslibria-converter';

const converter = createConverter();

export async function convertFromQueue(inputPath: string, outputPath: string) {
  return converter.convertBook(inputPath, {
    outputPath,
    returnBuffer: false,
  });
}

Inspection is useful when you want to show a title, author, warnings list, or cover entry before deciding whether to run a full conversion. It is also a good fit for validation endpoints and content triage tools.

import { inspectBook } from 'dyslibria-converter';

const inspection = await inspectBook('./books/source.epub');

console.log(inspection.title);
console.log(inspection.author);
console.log(inspection.coverEntryName);
console.log(inspection.warnings);

Pass a `logger` callback to receive structured events for each stage of the pipeline. Each event includes a log level, a step name, a message, and optional details.

This is the easiest way to wire the converter into your own app logs without parsing arbitrary console output.

import { convertBook } from 'dyslibria-converter';

await convertBook('./books/source.epub', {
  outputPath: './books/source.dyslibria.epub',
  logger(event) {
    if (event.level === 'debug') return;

    console.log(`[${event.level}] [${event.step}] ${event.message}`, event.details ?? {});
  },
});

• `InvalidEpubError` for archives that are not valid EPUBs
• `ArchiveSafetyError` for extraction hazards such as zip-slip style paths or over-large archives
• `NoContentFilesError` when no HTML or XHTML content was found to process
• `ConversionStepError` when a specific pipeline stage fails and you want step context

If you do not pass `--output`, the CLI writes the result beside the input file using the pattern `name.dyslibria.epub`. If you do not pass `--preset` or `--profile`, the CLI uses Dyslibria Default.

npx dyslibria-convert convert ./books/input.epub
npx dyslibria-convert convert ./books/input.epub --preset intense-scaffolding
npx dyslibria-convert convert ./books/input.epub --profile ./profiles/custom-profile.json --output ./books/output.epub

The inspect command prints a formatted JSON object with title, author, warnings, and other metadata fields, which makes it handy inside shell scripts and CI checks.

npx dyslibria-convert inspect ./books/input.epub

Before publishing a new version, run the built-in release check. It covers unit and parity tests, the package build, and a dry-run pack step so you can confirm the published tarball shape before npm sees it.

npm test
npm run build
npm run release:check

Synthetic fixtures are essential, but real EPUB corpora catch the awkward edge cases that only appear in the wild. The package includes a regression runner so you can point the current build at a trusted local corpus before a release.

npm run build
npm run qa:real-world -- \
  --input-dir /path/to/raw-epubs \
  --output-dir ./reports/real-world-output \
  --report ./reports/real-world-regression.json

If you keep a hand-picked private manifest for especially valuable books, the real-world regression runner can process just that shortlist. This is a good habit when you have a known set of titles that historically reveal regressions.

npm run qa:real-world -- \
  --input-dir /path/to/raw-epubs \
  --manifest ./fixtures/local/release-candidate.json \
  --output-dir ./reports/regression-output \
  --report ./reports/regression-report.json