documents.js
A family of independent, MIT-licensed TypeScript packages for lossless, type-safe document conversion — OOXML (docx/pptx/xlsx), OpenDocument (odt/ods/odp), Markdown, EPUB, and PDF — sharing a common Zod-based schema layer, plus the CLI, MCP server, and web UI built on top of them.
This repository is a pnpm workspace: one repository, one lockfile, one CI pipeline, and one release run, holding every package in the family under packages/. Each package keeps its own version, its own changelog, its own npm release cadence, and its own README — consolidating the repositories did not merge the packages into one artifact, and there is no lockstep version shared between them. What is shared is everything that was previously copied: the workspace settings, the task pipeline, the git hooks, commit-message validation, dependency automation, and the release orchestration.
Getting started
Node 24 (pinned in .tool-versions) and pnpm 11.6.0 (pinned as packageManager in the root package.json) are the only prerequisites; corepack resolves the latter automatically. pnpm install resolves and links every package in one pass — there is no per-package install step.
No environment variable is required for a normal build/lint/test run. documents.js's examples suite regenerates its fixtures only when GENERATEEXAMPLES is set; pnpm test:corpus additionally expects the gitignored real-world conformance corpora to already be present locally (see each codec's own README for what it checks against).
Packages
The packages layer from foundation up to user-facing interfaces. Each depends only on the layers below it.
Foundation
| Package | What it is | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | document-schema.js | The canonical, format-agnostic content and document-tree schema shared by every codec, plus the structural transform between them (decompose/flattenTree/factorStyles/assembleTree, converting a flat ContentDocument to and from the tree-form DocumentTree). Free of any format-specific or I/O behaviour: the transform lives here because every codec depends on this package and none of them depends on documents.js, so it is the only layer a codec can reach to expose DocumentTree publicly without a dependency cycle. | | byte-codec | Generic byte-level primitives (ByteWriter, ByteReader, CRC-32, deflate/inflate, base64) and PNG/JPEG image encoding and decoding, with zero knowledge of any document format. The base64 pair is the one every codec shares for an image payload or a data: URI, so no codec carries its own. | | document-outline.js | Utilities for consumers holding a tree-form DocumentTree: the TOC outline projection, effective-property resolution, and the flatten/leaf-text/stable-hash helpers. Depends on the schema alone, and is consumed by the interface packages rather than by the codecs. | | archive-codec | Recursive archive (ZIP-in-ZIP) detection and walking with depth and cumulative decompressed-size guards, plus bounded classic OLE compound-file ([MS-CFB]) reading, conformant [MS-CFB] writing, and OLE Package stream reading and writing — zero document-format knowledge. Consumed by ooxml.js, whose pptx (p:oleObj) and docx (o:OLEObject) OLE reading detects a ZIP-payload embedded object through it and decodes the nested package as a content document, and unwraps the classic .bin compound-file spelling through its CFB reader to the same nested decode; the writer is the container the legacy binary codecs need before any of them can gain a write path, and rtf-codec builds its own Package-stream-wrapped embedded objects through the identical pair. | | document-compute.js | Units-typed evaluation over the schema's MathExpression: evaluate() for point values and bounded intervals through one interpreter with exact-rational unit conversion, plus solveFor() numeric root-finding on one unknown. Depends on the schema alone; consumed by document-mcp's computeformula tool, not by any codec or the conversion engine. | | excel-number-format | A tokenizing classifier for Excel's number-format mini-language (ECMA-376 Part 1 §18.8.30, which BIFF8's [MS-XLS] 2.4.126 defers to): deciding whether a numeric cell's format code says percentage, currency, date, time, elapsed duration, or plain number. No document-format knowledge of its own; shared by ooxml.js's xlsx support and xls-codec's BIFF8 reading, since the two formats inherit the identical mini-language. |
Format codecs
Each converts one document format to and from the shared schema, built on document-schema.js:
| Package | Formats | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ooxml.js | OOXML packages (docx, pptx, xlsx) to and from JSON. | | odf.js | OpenDocument packages (odt, ods, odp, odg) to and from JSON, plus read and write support for the pre-OASIS OpenOffice.org 1.x documents ODF was based on (sxw, sxc, sxi, sxd). | | markdown-codec | CommonMark+GFM to and from the shared content schema. | | pdf-codec | Parses arbitrary real-world PDFs and generates new ones, also depending on byte-codec. | | epub-codec | Flowable EPUB 2/3 to and from the shared content schema; writes EPUB 3 only. | | rtf-codec | Rich Text Format to and from the shared content schema; hand-written tokenizer, destination state machine, and header-table parsers, since RTF is tokenised text rather than XML, also depending on archive-codec for the [MS-CFB] container an embedded object's \objdata carries. | | wpd-codec | WordPerfect 6.x-X6 (.wpd) to the shared content schema; read-only, and under active development. | | doc-codec | The pre-2007 Word Binary File Format (.doc, [MS-DOC]) to and from the shared content schema, also depending on archive-codec for its [MS-CFB] container; write support covers character/paragraph formatting (including numbered/bulleted lists and named styles), multiple sections, tables, cell decoration, PNG/JPEG inline images, page breaks, footnote/endnote/comment bodies and header/footer stories, and metadata, with style-inherited formatting, note references, embedded objects, and construct-boundary markers still gaps — see the package's own README for its exact scope. | | xls-codec | Legacy Excel Binary File Format (.xls, BIFF8) to and from the shared content schema, also depending on archive-codec for its [MS-CFB] container; write support covers cell values, merges, row/column sizing, number formats, cell background/border decoration, cell alignment, print settings, same-sheet formulas, and images/embedded objects (charts excepted), with per-cell fonts and defined names the remaining permanent gaps — see the package's own README for its exact scope. | | ppt-codec | PowerPoint 97-2003 binary presentations (.ppt, [MS-PPT]) to and from the shared content schema, also depending on archive-codec for its [MS-CFB] container and byte-codec for OLE-storage decompression; the write side covers text-box, picture, and table shapes with rotation and per-shape text insets, OLE-embedded objects are detected and linked both ways through an injected serialise/decode port pair (this single-format package depends on no sibling codec to turn an embedded object's own nested content into bytes or back), and both directions remain under active development. |
Rendering backends
| Package | What it is | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | pdf-raster-cpu | The pure-software reference implementation of pdf-codec's PageRasteriser port: renders a PDF page, or one located region of one, to PNG bytes with a scanline rasteriser that has no canvas dependency, so it runs identically under Node, a browser Worker, and workerd. pdf-codec defines