Skip to content

feat(archive-codec): write conformant [MS-CFB] compound files #863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mearman merged 3 commits into from
Sep 3, 2026
Merged

feat(archive-codec): write conformant [MS-CFB] compound files #863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7eab289
feat(archive-codec): write conformant [MS-CFB] compound files
Mearman Sep 3, 2026
6adf52d
docs(archive-codec): describe the compound-file write path
Mearman Sep 3, 2026
360b588
docs: record that archive-codec writes compound files, not only reads…
Mearman Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions COMPARISON.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Scope: how the [documents.js ecosystem](README.md) compares against real alterna

**documents.js counterpart:** byte-codec, archive-codec

This is the category where documents.js's 'hand-written, dependency-minimal' claim is least differentiating — essentially every alternative is also hand-written or ported-from-C with no dependencies. The real question byte-codec has to answer is why it exists rather than depending on fflate. For archive-codec, the closest true counterpart is SheetJS's cfb (same MS-CFB target, plus limited writing) — but cfb has no ZIP awareness, and no ZIP library has OLE/CFB support, so the combination of recursive ZIP-in-ZIP walking with depth/size guards alongside bounded CFB reading in one package is genuinely unmatched, though narrow.
This is the category where documents.js's 'hand-written, dependency-minimal' claim is least differentiating — essentially every alternative is also hand-written or ported-from-C with no dependencies. The real question byte-codec has to answer is why it exists rather than depending on fflate. For archive-codec, the closest true counterpart is SheetJS's cfb, which targets MS-CFB in both directions as archive-codec now does — but cfb has no ZIP awareness, and no ZIP library has OLE/CFB support, so the combination of recursive ZIP-in-ZIP walking with depth/size guards alongside bounded CFB reading and writing in one package is genuinely unmatched, though narrow.

| Package / service | Direction | Approach | Deployment | Licence | Pricing model | Status |
| -------------------------------------------------------------- | ------------ | ------------ | ---------- | ------------------------- | ------------------ | --------- |
Expand Down Expand Up @@ -116,7 +116,7 @@ Standard CRC-32/CRC-32C checksum implementation with a bundled CLI. (npm · v1.2

Pure-JS MS-CFB (classic OLE) container reader/writer, part of SheetJS. (npm · v1.2.2 · 2022-04-06)

**vs. documents.js:** Closest direct counterpart to archive-codec's CFB reader — same approach, same target — and goes further with limited CFB writing, but has zero ZIP awareness.
**vs. documents.js:** Closest direct counterpart to archive-codec's CFB support — same approach, same target, and the same two directions now that archive-codec writes compound files as well as reading them — but has zero ZIP awareness.

**Free tier:** N/A — the package itself is free and open source; no paid tiers exist.

Expand Down
14 changes: 7 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@ The packages layer from foundation up to user-facing interfaces. Each depends on

### Foundation

| Package | What it is |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`document-schema.js`](packages/document-schema.js/README.md) | 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`](packages/byte-codec/README.md) | Generic byte-level primitives (`ByteWriter`, `ByteReader`, CRC-32, deflate/inflate) and PNG/JPEG image encoding and decoding, with zero knowledge of any document format. |
| [`document-outline.js`](packages/document-outline.js/README.md) | 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`](packages/archive-codec/README.md) | Recursive archive (ZIP-in-ZIP) detection and walking with depth and cumulative decompressed-size guards, plus bounded classic OLE compound-file ([MS-CFB]) reading and OLE Package stream unwrapping — 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. |
| [`document-compute.js`](packages/document-compute.js/README.md) | 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; a leaf nothing else depends on yet — it is not wired into any conversion pipeline. |
| Package | What it is |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`document-schema.js`](packages/document-schema.js/README.md) | 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`](packages/byte-codec/README.md) | Generic byte-level primitives (`ByteWriter`, `ByteReader`, CRC-32, deflate/inflate) and PNG/JPEG image encoding and decoding, with zero knowledge of any document format. |
| [`document-outline.js`](packages/document-outline.js/README.md) | 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`](packages/archive-codec/README.md) | 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 unwrapping — 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. |
| [`document-compute.js`](packages/document-compute.js/README.md) | 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; a leaf nothing else depends on yet — it is not wired into any conversion pipeline. |

### Format codecs

Expand Down
Loading
Loading