yom-format

TypeScript implementation of the YOM packfile format: a read-only, single-file package for scanned books (AVIF pages, a FlatBuffers index, and optional OCR / full-text search data). This package provides a reader, writer, and validator, plus an optional browser-side PDF → .yom conversion pipeline.

The format specification lives at docs/format-spec.md in the main repository; this package is one of two implementations kept byte-compatible with it (the other is the Swift package in swift/, used by Yomu).

Install

npm install yom-format

Read a .yom file

import { YOMPackfileReader } from "yom-format";

const bytes = new Uint8Array(await readFile("book.yom")); // however you load the file
const reader = await YOMPackfileReader.open(bytes);

console.log(reader.title, reader.pageCount);
const avifPage = await reader.pageImage(0); // AVIF bytes for page 0
const avifThumb = await reader.thumbnailImage(0);

Validate a .yom file

import { validateYOM, YOMValidationError } from "yom-format";

try {
  await validateYOM(bytes);
  console.log("valid");
} catch (error) {
  if (error instanceof YOMValidationError) {
    console.error("invalid package:", error.message);
  } else {
    throw error;
  }
}

The main entry also exports writeYOM (build a package from pages + blobs), buildSearchIndex / decodePostings (the bigram search index), and the lower-level constants / header helpers used by all three.

PDF → .yom conversion (browser only)

Converting a PDF into a .yom package is a separate subpath so the core reader/writer stays free of pdf.js and image-codec dependencies:

import { convertPdfToYom } from "yom-format/pipeline";

const yomBytes = await convertPdfToYom(pdfBytes, {
  title: "Book Title",
  onProgress: (stage, fraction) => console.log(stage, fraction),
});

This pipeline renders with pdf.js onto a Canvas/OffscreenCanvas, encodes pages and thumbnails as AVIF, and writes a validated package — it requires a DOM environment and a bundler that can handle pdf.js's worker and the WebAssembly codecs (@bokuweb/zstd-wasm, @jsquash/avif); it will not run under plain Node. It is not bundled with a Web Worker wrapper — wrap convertPdfToYom in your own worker if you need conversion off the main thread (see src/worker/convert.worker.ts in the repository for the pattern this project uses internally).

Links

• Format specification: docs/format-spec.md
• Source repository: github.com/juntaki/yom-format
• Built for Yomu, an iOS reader for scanned PDFs

License

MIT