officeparser 7.2.3 → 7.4.0

package/README.md

@@ -2,9 +2,9 @@
 
 A robust, strictly-typed **Node.js and Browser** library for parsing office files into a rich **Abstract Syntax Tree (AST)** and generating high-fidelity output in multiple formats.
 
-**Parses:** [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`odt`](https://en.wikipedia.org/wiki/OpenDocument) · [`odp`](https://en.wikipedia.org/wiki/OpenDocument) · [`ods`](https://en.wikipedia.org/wiki/OpenDocument) · [`pdf`](https://en.wikipedia.org/wiki/PDF) · [`rtf`](https://en.wikipedia.org/wiki/Rich_Text_Format) · [`csv`](https://en.wikipedia.org/wiki/Comma-separated_values) · [`md`](https://en.wikipedia.org/wiki/Markdown) · [`html`](https://en.wikipedia.org/wiki/HTML)
+**Parses:** [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`odt`](https://en.wikipedia.org/wiki/OpenDocument) · [`odp`](https://en.wikipedia.org/wiki/OpenDocument) · [`ods`](https://en.wikipedia.org/wiki/OpenDocument) · [`pdf`](https://en.wikipedia.org/wiki/PDF) · [`rtf`](https://en.wikipedia.org/wiki/Rich_Text_Format) · [`csv`](https://en.wikipedia.org/wiki/Comma-separated_values) · [`md`](https://en.wikipedia.org/wiki/Markdown) · [`html`](https://en.wikipedia.org/wiki/HTML) · [`epub`](https://en.wikipedia.org/wiki/EPUB)
 
-**Generates:** `Markdown` · `HTML` · `CSV` · `RTF` · `PDF` · `Plain Text` · `RAG Chunks`
+**Generates:** `Markdown` · `HTML` · `CSV` · `RTF` · `PDF` · `EPUB` · `Plain Text` · `RAG Chunks`
 
 [![npm version](https://badge.fury.io/js/officeparser.svg)](https://badge.fury.io/js/officeparser)
 [![Total Downloads](https://img.shields.io/npm/dt/officeparser.svg)](https://www.npmjs.com/package/officeparser)
@@ -42,6 +42,8 @@ A robust, strictly-typed **Node.js and Browser** library for parsing office file
 - [Native RAG Chunking](#native-rag-chunking)
 - [The AST Structure](#the-ast-structure)
 - [Deep Dive: Document Components](#deep-dive-document-components)
+- [Markdown Dialect Support](#markdown-dialect-support)
+- [EPUB Support](#epub-support)
 - [Performance Highlights](#performance-highlights)
 - [Advanced AST Usage](#advanced-ast-usage)
 - [Configuration Reference](#configuration-reference)
@@ -54,12 +56,14 @@ A robust, strictly-typed **Node.js and Browser** library for parsing office file
   - [PdfGeneratorConfig](#pdfgeneratorconfig)
   - [CsvGeneratorConfig](#csvgeneratorconfig)
   - [TextGeneratorConfig](#textgeneratorconfig)
+  - [metadataOverrides](#metadataoverrides)
   - [OfficeConverterConfig](#officeconverterconfig)
   - [ChunkingConfig](#chunkingconfig)
 - [OCR Scheduler & Resource Management](#ocr-scheduler--resource-management)
 - [Browser Usage](#browser-usage)
 - [Troubleshooting & Common Issues](#troubleshooting--common-issues)
 - [Known Limitations](#known-limitations)
+- [Security & Trust Boundary](#security--trust-boundary)
 - [Contributing](#contributing)
 
 ---
@@ -93,6 +97,9 @@ npx officeparser data.xlsx --to=csv --csvDelimiter=";"
 # Generate RAG chunks
 npx officeparser document.pdf --to=chunks
 
+# Convert DOCX to EPUB (--extractAttachments is required to embed images)
+npx officeparser book.docx --extractAttachments --to=epub --output=book.epub
+
 # Overriding file extension mapping
 npx officeparser my_document --fileType=docx --to=json
 ```
@@ -106,9 +113,9 @@ npx officeparser my_document --fileType=docx --to=json
 
 | Flag | Values | Default | Description |
 |------|--------|---------|-------------|
-| `--to` | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | Output format |
+| `--to` | `json\|text\|md\|html\|csv\|rtf\|pdf\|epub\|chunks` | `json` | Output format |
 | `--output` | path | — | Write output to a file |
-| `--fileType` | `docx\|xlsx\|pptx\|odt\|odp\|ods\|pdf\|rtf\|csv\|md\|html` | — | Explicitly override input file type detection |
+| `--fileType` | `docx\|xlsx\|pptx\|odt\|odp\|ods\|pdf\|rtf\|csv\|md\|html\|epub` | — | Explicitly override input file type detection |
 | `--ocr` | boolean | `false` | Enable OCR for images |
 | `--extractAttachments` | boolean | `false` | Extract images/charts as Base64 |
 | `--ignoreNotes` | boolean | `false` | Ignore footnotes/endnotes/speaker notes |
@@ -126,8 +133,8 @@ npx officeparser my_document --fileType=docx --to=json
 | `--includeFormatting` | boolean | `true` | Include formatting style map matching |
 | `--renderMetadata` | boolean | `false` | Render metadata as visible content in the generated output |
 | `--htmlConfig.containerWidth` | string \| number | `auto` | HTML output container width (e.g. `900px`, `100%`) |
-| ~~`--format`~~ | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | **Deprecated.** Use `--to` |
-| ~~`--toText`~~ | `true\|false` | `false` | **Deprecated.** Use `--to=text` |
+| ~~`--format`~~ | `json\|text\|md\|html\|csv\|rtf\|pdf\|epub\|chunks` | `json` | **Deprecated.** Use `--to` |
+| ~~`--toText`~~ | `true\|false` | `false` | **Deprecated.** Use `--to=text`, which keeps footnote text and image placeholders by default (both switchable); this flag drops them unconditionally |
 | ~~`--ocrLanguage`~~ | string | `eng` | **Deprecated.** Use `--ocrConfig.language` |
 | ~~`--putNotesAtLast`~~ | `true\|false` | `false` | **Deprecated and ignored.** Notes are attached structurally to their nodes. |
 | ~~`--outputErrorToConsole`~~ | `true\|false` | `false` | **Deprecated.** Use `--verbose` |
@@ -269,14 +276,57 @@ const { value: pdfBytes }           = await ast.to('pdf'); // Uint8Array
 
 ### `ast.toText()`: Quick Text Extraction
 
-> [!NOTE]
-> `toText()` is **synchronous** and deprecated in favour of the async `ast.to('text')`.
-> It remains available for backward compatibility.
+> [!WARNING]
+> `toText()` is **synchronous** and deprecated in favour of the async `ast.to('text')`. It remains
+> available for backward compatibility, but it is the older, less capable renderer: it has no
+> configuration at all, so footnote/endnote text and image placeholders are **unconditionally
+> dropped** rather than being something you can ask for. Prefer `.to('text')` for new code.
 
 ```js
 const text = ast.toText(); // synchronous, returns plain string
 ```
 
+#### Migrating to `.to('text')`
+
+`.to('text')` is asynchronous and configurable. Its defaults render tables as aligned grids, lists
+with markers/indentation, and include notes and image placeholders:
+
+```js
+// Default: aligned table grids, list markers, notes, image placeholders
+const { value } = await ast.to('text');
+
+// Deliberate opt-out: the combination closest to toText()'s shape
+const { value } = await ast.to('text', {
+    includeImages: false,
+    textConfig: { preserveLayout: false, renderNotes: false },
+});
+```
+
+**At its default configuration, `.to('text')` emits everything `toText()` emits.** Verified across
+every bundled fixture in all 12 supported formats, in both layout modes: no word `toText()` produces
+is missing from `.to('text')`. It additionally emits notes and image placeholders, which `toText()`
+never produces, and it renders merged table cells correctly (`toText()` glues a two-cell row into
+`OneThree`, where `.to('text')` gives `One Three`).
+
+Notes and images are **configuration, not intrinsic behavior**. They are on by default and you can
+turn them off. The real difference from `toText()` is that they are a choice at all:
+
+| | `toText()` | `.to('text')` | governed by |
+|---|---|---|---|
+| Tables | one cell per line | aligned grid, or tab-separated | `textConfig.preserveLayout` (default `true`) |
+| Lists | plain text | markers + indentation, or plain | `textConfig.preserveLayout` (default `true`) |
+| Footnotes/endnotes | never emitted | emitted by default | `textConfig.renderNotes` (default `true`) |
+| Image placeholders | never emitted | emitted by default | `includeImages` (default `true`) |
+| Chart data series | emitted | emitted | n/a |
+
+Nothing about `.to('text')` forces the richer output on you. The defaults simply start from the more
+complete document, and the opt-out above gets you back to `toText()`'s shape deliberately rather
+than by having no alternative.
+
+Spreadsheets (CSV/ODS/XLSX) are unaffected by `preserveLayout`: it governs `table`/`list` nodes,
+while spreadsheet content is `sheet`/`row`/`cell`. There the default aligned grid is the most
+faithful rendering.
+
 ---
 
 ## OfficeGenerator
@@ -306,13 +356,16 @@ const { value: html } = await OfficeGenerator.generate(ast, 'html', {
 const { value: csv } = await OfficeGenerator.generate(ast, 'csv');
 ```
 
-**Supported destinations:** `'text'` · `'md'` · `'html'` · `'csv'` · `'rtf'` · `'pdf'` · `'chunks'`
+**Supported destinations:** `'text'` · `'md'` · `'html'` · `'csv'` · `'rtf'` · `'pdf'` · `'epub'` · `'chunks'`
 
 > [!NOTE]
 > **PDF generation** requires the optional `puppeteer` peer dependency:
 > ```bash
 > npm install puppeteer
 > ```
+>
+> **EPUB generation with images** requires `extractAttachments: true` on the parse step that
+> produced the AST — see [EPUB Support](#epub-support).
 
 ---
 
@@ -440,10 +493,10 @@ interface OfficeChunk {
 
 ```text
 OfficeParserAST
-├── type: 'docx' | 'pdf' | 'xlsx' | 'csv' | 'md' | ...  (11 formats)
+├── type: 'docx' | 'pdf' | 'xlsx' | 'csv' | 'md' | 'epub' | ...  (12 formats)
 ├── metadata: { author, title, created, modified, keywords, customProperties, nativeProperties, styleMap, ... }
 ├── content: [ OfficeContentNode ]
-│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | 'comment' | ...
+│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | 'comment' | 'admonition' | 'embed' | 'definitionList' | ...
 │   ├── text: string  (concatenated text of node + all descendants)
 │   ├── children: [ OfficeContentNode ]  (recursive structural children)
 │   ├── notes: [ OfficeContentNode ]     (footnotes/endnotes/slide notes attached to this node)
@@ -463,7 +516,7 @@ OfficeParserAST
 │   └── chartData?: { title, dataSets, labels }
 ├── warnings: OfficeIssue[]  (non-fatal issues from the parsing phase)
 ├── to(format, config?)  (format: 'html'|'md'|'text'|'csv'|'rtf'|'pdf'|'chunks', returns { value, messages })
-└── ~~toText()~~             (Deprecated: use .to('text') instead)
+└── ~~toText()~~             (Deprecated: use .to('text'); drops footnotes + image placeholders)
 ```
 
 ### `OfficeIssue`: Warning / Error Object
@@ -596,6 +649,94 @@ console.log(ast.metadata.nativeProperties);
 // PDF:  { Title: 'Report', XMP: { ... } }
 ```
 
+### 8. Admonitions, Embeds & Definition Lists
+
+```text
+Admonition Node (type: 'admonition')
+├── metadata: { admonitionType: 'note' | 'tip' | 'important' | 'warning' | 'caution', title?: string }
+└── children: [ Paragraph | List | ... ]   (block content)
+
+Embed Node (type: 'embed')
+└── metadata: { embedType: 'youtube', videoId: string, url?: string, width?: string, align?: string }
+
+Definition List Node (type: 'definitionList')
+└── children:
+    ├── Definition Term (type: 'definitionTerm')
+    └── Definition Description (type: 'definitionDescription')
+```
+
+- `admonition` round-trips through both Markdown (`> [!NOTE]` / `:::note ... :::`) and HTML (`<div class="admonition admonition-note" data-type="note">`)
+- `embed` currently models YouTube videos; HTML round-trips via `<div data-youtube-video="ID">`, Markdown falls back to a raw HTML block or a plain link
+- Abbreviations (`*[HTML]: Hypertext Markup Language`) are stored as `TextMetadata.abbreviationTitle` on the abbreviated text node rather than as a separate node type
+
+---
+
+## Markdown Dialect Support
+
+Beyond CommonMark/GFM basics, `MarkdownParser`/`MarkdownGenerator` support an extended dialect aimed at
+full-fidelity round-tripping with rich Markdown editors. Every construct below parses to a first-class
+AST node/metadata field and regenerates back to the canonical syntax shown, so `.md → AST → .md` is
+idempotent and `.md → AST → HTML → AST → .md` survives unchanged.
+
+| Feature | Markdown syntax | AST representation |
+|---|---|---|
+| Task lists (GFM) | `- [x] Done` / `- [ ] Todo` | `ListMetadata.isTask` / `.checked` |
+| Admonitions | `> [!NOTE]` (also accepts GLFM `:::note ... :::` on import) | `type: 'admonition'`, `AdmonitionMetadata` |
+| Footnotes | `Text[^1]` + `[^1]: Definition` | `type: 'note'`, keyed by footnote id |
+| Definition lists | `Term\n: Definition` | `type: 'definitionList'` / `'definitionTerm'` / `'definitionDescription'` |
+| Abbreviations | `*[HTML]: Hypertext Markup Language` | `TextMetadata.abbreviationTitle` |
+| Attribute lists | `![alt](img.png){width=50% .centered}` | `ImageMetadata.width` / `.align`, `TableMetadata.align` |
+| Citations | `[@smith2024]` | `TextMetadata.citationKey` |
+| Wikilinks | `[[Page]]` / `[[Page\|Alias]]` | `TextMetadata.wikilink`, `.link`, `.linkType` |
+| Inline/block math | `$E=mc^2$` / `` $$...$$ `` | `TextMetadata.math` (`'inline' \| 'block'`) |
+| Frontmatter arrays | `tags: [a, b]` or `tags: ["a","b"]` | Real array in `metadata.customProperties`/`nativeProperties` |
+| MDX components (import-only) | `<Component prop="x">...</Component>` | Stripped; inner Markdown is kept. Never generated back. |
+
+> [!NOTE]
+> MDX/JSX stripping is one-directional (parse-only) — officeParser never authors JSX back into Markdown.
+> Wikilink enable/disable and citekey→bibliography resolution are application-level concerns; officeParser
+> always parses/generates the syntax itself.
+
+The same round-trip fidelity extends to HTML, so content saved from a rich-text editor survives a
+save→reload cycle:
+
+| HTML attribute | AST field | Notes |
+|---|---|---|
+| `data-width` / `data-align` / inline `style="width:…"` on `<img>` | `ImageMetadata.width` / `.align` | |
+| `data-align` on `<table>` | `TableMetadata.align` | |
+| `colspan` / `rowspan` on `<td>`/`<th>` | `CellMetadata.colSpan` / `.rowSpan` | Previously dropped on HTML import — merged cells now survive a save→reload cycle |
+| `<div data-youtube-video="ID">` / `<iframe src="...youtube.com...">` | `type: 'embed'` | |
+| `<ul data-type="taskList">` / `<li data-checked>` | `ListMetadata.isTask` / `.checked` | |
+
+---
+
+## EPUB Support
+
+EPUB files are ZIP archives of XHTML content plus an OPF manifest — `EpubParser` unzips the archive,
+resolves the spine's reading order from `content.opf`, and parses each XHTML document through the
+existing `HtmlParser`, so EPUB content shares the same AST shape (and the same Markdown-dialect
+fidelity above) as every other format. Dublin Core metadata (`dc:title`, `dc:creator`, `dc:description`,
+`dc:subject`, `dc:date`, `dc:publisher`, `dc:language`, `dc:identifier`) maps into `ast.metadata` /
+`ast.metadata.nativeProperties`, and cover art is exposed via `metadata.customProperties.coverImageName`.
+
+`EpubGenerator` renders the AST through `HtmlGenerator` and packages the result as a minimal, valid
+EPUB 3 (`mimetype`, `META-INF/container.xml`, an OPF manifest, a nav document, and one XHTML chapter).
+
+> [!IMPORTANT]
+> **Pass `extractAttachments: true` when converting to or from EPUB if the document has images.**
+> Without it, the parser never pulls embedded image bytes out of the source document, so there is
+> nothing for the EPUB generator to package — images silently disappear even though everything else
+> converts correctly. Images are packaged as real zip entries (`OEBPS/images/...`) declared in the OPF
+> manifest, not `data:` URIs — most EPUB reading systems do not render `data:` URIs in image `src`.
+>
+> This only matters for the two-step `OfficeParser.parseOffice()` → `OfficeGenerator.generate()` API
+> and the CLI. [`OfficeConverter.convert()`](#officeconverter-one-step-api) enables `extractAttachments`
+> automatically unless you explicitly set `generatorConfig.includeImages: false`.
+>
+> ```bash
+> npx officeparser book.docx --extractAttachments --to=epub --output=book.epub
+> ```
+
 ---
 
 ## Performance Highlights
@@ -768,6 +909,7 @@ Options shared by all generator formats. Pass to `OfficeGenerator.generate(ast,
 | `includeFormatting` | `boolean` | `true` | Include bold/italic/colors/sizes in output |
 | `generateIds` | `boolean` | `true` | Add slug-based `id` attributes to headings |
 | `renderMetadata` | `boolean` | `false` | Render title/author as visible header block |
+| `metadataOverrides` | `MetadataOverrides` | `{}` | Override the metadata embedded in the output, merged per field over `ast.metadata` |
 | `includeImages` | `boolean` | `true` | Include image nodes in output |
 | `includeCharts` | `boolean` | `true` | Include interactive charts (HTML only) |
 | `ignoreInternalLinks` | `boolean` | `false` | Strip bookmarks and internal anchors from output |
@@ -852,7 +994,7 @@ Pass as `htmlConfig` inside `GeneratorConfig`.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `standalone` | `boolean` | `true` | Wrap output in a full `<html>` document with CSS |
+| `standalone` | `boolean \| StandaloneConfig` | `true` | Controls the HTML "document envelope" — see below |
 | `chartJsSrc` | `string` | jsDelivr CDN | URL for the Chart.js library |
 | `containerWidth` | `string \| number` | `'auto'` | Max width of the content container. Positive number (px), CSS length string (`'900px'`, `'100%'`, `'60vw'`), or `'auto'`. Invalid values fall back to `'auto'` with an `INVALID_CONTAINER_WIDTH` warning |
 | `customCss` | `string` | `''` | Raw CSS injected into the `<style>` block; use this to override built-in styles |
@@ -861,6 +1003,49 @@ Pass as `htmlConfig` inside `GeneratorConfig`.
 | `injections.bodyStart` | `string` | `''` | Raw HTML injected after `<body>` |
 | `injections.bodyEnd` | `string` | `''` | Raw HTML injected before `</body>` |
 
+#### `standalone`: granular envelope control
+
+`standalone` conflates several independent decisions: whether to emit the `<!doctype>/<html>/<head>/
+<body>` shell, how CSS is delivered, and whether to inject scripts/meta tags/injections. The boolean
+shorthand still works — **`true`/omitted turns every part on** (a complete document); **`false` turns
+every part off** (a bare content fragment, safe to drop into a page you don't control). Pass an
+object instead for granular control; any field you omit defaults to its "on" (standalone) value:
+
+| `StandaloneConfig` field | Type | Default | Description |
+|--------|------|---------|-------------|
+| `document` | `boolean` | `true` | Wrap in `<!DOCTYPE html><html><head>…</head><body>…</body></html>` |
+| `metaTags` | `boolean` | `true` | Emit `<title>`/`<meta>` tags. Only meaningful when `document` is true |
+| `styles` | `'full' \| 'scoped' \| 'none'` | `'full'` | See below |
+| `scripts` | `boolean` | `true` | Emit the Chart.js CDN loader and spreadsheet-interactivity `<script>` tags |
+| `headInjections` | `boolean` | `true` | Apply `injections.headStart`/`headEnd`. Only meaningful when `document` is true |
+| `bodyInjections` | `boolean` | `true` | Apply `injections.bodyStart`/`bodyEnd` — applies even to a bare fragment |
+
+`styles` controls how the built-in stylesheet is delivered:
+- **`'full'`** — the complete stylesheet using global selectors (`body`, `h1`, `table`, …). This is
+  what `standalone: true` has always emitted.
+- **`'scoped'`** — the same styling, scoped under the fragment's own wrapper via CSS `@scope` so it
+  cannot leak onto a host page's elements. Requires a modern engine (Chrome 118+, Safari 17.4+,
+  Firefox 128+); for universal support use `'none'` (bring your own CSS) or `'full'`.
+- **`'none'`** — no stylesheet at all; the host page (or rich-text editor, or EPUB reader) supplies
+  its own styling.
+
+```js
+// A styled fragment to embed in your own page, without a document shell:
+await ast.to('html', { htmlConfig: { standalone: { document: false } } });
+
+// The same, but with styles scoped so they can't leak onto your page's own elements:
+await ast.to('html', { htmlConfig: { standalone: { document: false, styles: 'scoped' } } });
+
+// A completely bare fragment (no shell, no styles, no scripts) — e.g. for a rich-text editor:
+await ast.to('html', { htmlConfig: { standalone: false } });
+```
+
+> [!NOTE]
+> **Behavior change from `standalone: false`:** previously this emitted a fragment with a *global,
+> unscoped* `<style>` block. It now emits a genuinely bare fragment (no `<style>` at all), matching
+> "every part off." If you relied on the old styled-fragment behavior, pass
+> `{ document: false }` (or `{ document: false, styles: 'full' }`) instead.
+
 ### MdGeneratorConfig
 
 Pass as `mdConfig` inside `GeneratorConfig`.
@@ -906,6 +1091,52 @@ Pass as `textConfig` inside `GeneratorConfig`.
 |--------|------|---------|-------------|
 | `newlineDelimiter` | `string` | `'\n'` | String inserted between structural blocks |
 | `preserveLayout` | `boolean` | `true` | Render tables with aligned columns using whitespace |
+| `renderNotes` | `boolean` | `true` | Append the collected footnote/endnote section |
+
+### metadataOverrides
+
+Part of the common `GeneratorConfig` (not format-specific). Overrides the metadata embedded in
+generated output, applied **per field** on top of `ast.metadata`, so setting one field leaves the
+rest of the parsed metadata intact. `ast.metadata` itself is never mutated, so the same AST can be
+generated repeatedly with different metadata.
+
+| Field | Type | Written as |
+|-------|------|-----------|
+| `title` | `string` | HTML `<title>`/`<meta>`, EPUB `dc:title`, Markdown frontmatter, RTF `\title` |
+| `author` | `string` | HTML `<meta name="author">`, EPUB `dc:creator`, frontmatter, RTF `\author` |
+| `description` | `string` | HTML `<meta name="description">`, EPUB `dc:description`, frontmatter |
+| `subject` / `keywords` / `lastModifiedBy` | `string` | Where the destination format has a slot |
+| `created` / `modified` | `Date` | HTML `dcterms.*`, EPUB `dcterms:modified`, frontmatter |
+| `language` | `string` | EPUB `dc:language` |
+| `custom` | `Record<string, string \| number \| boolean \| Date>` | HTML `<meta name="custom:KEY">`, Markdown frontmatter |
+
+```js
+// Rebrand the output without touching the parsed document
+const { value } = await ast.to('html', {
+    metadataOverrides: { title: 'Q4 Report', author: 'Acme Inc', custom: { department: 'Finance' } },
+});
+```
+
+#### Dates
+
+`created` and `modified` take a `Date`. When `modified` is unset, officeParser uses the source
+document's own `ast.metadata.modified`, falling back to the current time only if the document has
+none. Dates outside the 1980-2099 range representable in a ZIP timestamp are clamped where EPUB
+writes them onto zip entries.
+
+```js
+const { value } = await ast.to('epub', {
+    metadataOverrides: { modified: new Date('2024-01-01T00:00:00Z') },
+});
+```
+
+#### Not every format can represent every field
+
+HTML `<meta>` tags and Markdown frontmatter are open vocabularies and accept anything. EPUB's OPF
+is a closed Dublin Core vocabulary and RTF's `\info` group has a fixed set of control words, so a
+`custom` entry has nowhere to go in either. Rather than dropping it silently, those generators
+report it through `onWarning` (`OfficeWarningType.METADATA_NOT_REPRESENTABLE`) and continue; the
+named fields still apply.
 
 ---
 
@@ -1028,7 +1259,7 @@ const handleFile = async (event) => {
     const file = event.target.files[0];
     const buffer = await file.arrayBuffer();
     const ast = await OfficeParser.parseOffice(new Uint8Array(buffer));
-    console.log(ast.toText());
+    console.log((await ast.to('text')).value);
 };
 ```
 
@@ -1041,7 +1272,7 @@ const handleFile = async (event) => {
         const file = event.target.files[0];
         const buffer = await file.arrayBuffer();
         const ast = await officeParser.parseOffice(new Uint8Array(buffer));
-        console.log(ast.toText());
+        console.log((await ast.to('text')).value);
     }
 </script>
 ```
@@ -1076,7 +1307,7 @@ const ast = await officeParser.parseOffice(pdfArrayBuffer, {
 | Node.js process stays alive after finishing | Call `await officeParser.terminateOcr()` at end of script when OCR was used |
 | `"Worker not found"` in browser for PDF | Verify `pdfWorkerSrc` points to `pdf.worker.min.mjs` matching version `6.1.200` |
 | Low OCR accuracy | Verify `ocrConfig.language` matches the document language; quality depends on image resolution |
-| Out of memory on large Excel files | Call `ast.toText()` early and discard the AST object to allow garbage collection |
+| Out of memory on large Excel files | Call `await ast.to('text')` early and discard the AST object to allow garbage collection |
 | `md`/`html`/`csv` buffer not detected | Add `fileType: 'md'` (or `'html'`, `'csv'`) to config (these formats have no magic bytes) |
 | `IMPROPER_BUFFERS` error | Usually means no file extension and no `fileType` hint was provided for a buffer input |
 | PDF generation fails | Install the optional peer dependency: `npm install puppeteer` |
@@ -1092,6 +1323,35 @@ For a full debugging guide, visit the [Live Documentation](https://harshankur.gi
 
 ---
 
+## Security & Trust Boundary
+
+`officeParser` is a **parsing, generation, and conversion** library. Like any parser, its whole job
+is to open and interpret files it is handed, and those files may come from an untrusted source (a
+user upload, an email attachment, a scraped document). A parser that accepts arbitrary documents
+has a large and inherently open attack surface.
+
+I do sanitize output and apply hardening where I can: injection escaping across the
+HTML/CSS/URL/script/CSV/RTF/Markdown sinks, decompression limits, some resource and recursion
+bounds, and SSRF precautions during PDF rendering. I fix issues as I learn of them (see
+[CHANGELOG.md](CHANGELOG.md)). But this is **best-effort, not a guarantee.** A document parser of
+this size will have attack vectors I have not found or have not yet addressed, and no amount of
+internal hardening makes it safe to feed fully untrusted input without your own precautions.
+
+**Treat this as garbage in, garbage out.** The library does its best with what you give it, but
+responsibility for what you feed it, and for the effect a malicious file has on your system, rests
+with you. If you process files from untrusted sources, sanitize and validate them at your own
+boundary, and run the parsing in isolation appropriate to your threat model: sandboxing or
+containerization, memory and time limits, a low-privilege process, and the `abortSignal` and
+`decompressionLimits` options this library exposes. Do not rely on any single library's hardening
+as a complete defense.
+
+I am the sole maintainer, with no security team behind me. I take legitimate reports seriously and
+will fix what I reasonably can, but I cannot commit to a response or resolution timeline. The
+software is provided "AS IS" without warranty of any kind (see [LICENSE](LICENSE)). To report an
+issue privately, see [SECURITY.md](SECURITY.md).
+
+---
+
 **npm**: [https://npmjs.com/package/officeparser](https://npmjs.com/package/officeparser)
 
 **github**: [https://github.com/harshankur/officeParser](https://github.com/harshankur/officeParser)

package/dist/OfficeConverter.d.ts

@@ -42,6 +42,6 @@ export declare class OfficeConverter {
      * });
      * ```
      */
-    static convert<F extends string | Buffer | ArrayBuffer | Uint8Array, T extends SupportedFileType = InferFileTypeFromPath<F>>(file: F, destination: SupportedDestination<T>, config?: OfficeConverterConfig<SupportedDestination<T>, T>): Promise<ConversionResult<SupportedDestination<T>>>;
+    static convert<F extends string | Buffer | ArrayBuffer | Uint8Array, T extends SupportedFileType = InferFileTypeFromPath<F>, D extends SupportedDestination<T> = SupportedDestination<T>>(file: F, destination: D, config?: OfficeConverterConfig<D, T>): Promise<ConversionResult<D>>;
 }
 export {};

package/dist/OfficeConverter.js

@@ -65,6 +65,9 @@ class OfficeConverter {
             ...config?.generatorConfig,
             onWarning: config?.onWarning || config?.generatorConfig?.onWarning,
         };
+        // The spread widens the object to an inferred literal; it is a `GeneratorConfig<D>` by
+        // construction (config.generatorConfig is already typed for D, and onWarning is common to
+        // every destination), so the cast restates what the types otherwise lose.
         const result = await OfficeGenerator_js_1.OfficeGenerator.generate(ast, destination, generatorConfig);
         result.messages = [...(ast.warnings || []), ...result.messages];
         return result;

package/dist/OfficeGenerator.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfficeGenerator = void 0;
 const ChunkingGenerator_js_1 = require("./generators/ChunkingGenerator.js");
 const CsvGenerator_js_1 = require("./generators/CsvGenerator.js");
+const EpubGenerator_js_1 = require("./generators/EpubGenerator.js");
 const HtmlGenerator_js_1 = require("./generators/HtmlGenerator.js");
 const MarkdownGenerator_js_1 = require("./generators/MarkdownGenerator.js");
 const PdfGenerator_js_1 = require("./generators/PdfGenerator.js");
@@ -60,6 +61,9 @@ class OfficeGenerator {
             case 'chunks':
                 generator = new ChunkingGenerator_js_1.ChunkingGenerator(ast, config);
                 break;
+            case 'epub':
+                generator = new EpubGenerator_js_1.EpubGenerator(ast, config);
+                break;
             default:
                 throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.FORMAT_UNSUPPORTED, undefined, destination);
         }

package/dist/OfficeParser.d.ts

@@ -14,6 +14,7 @@
  * - CSV (Comma-Separated Values)
  * - MD (Markdown)
  * - HTML (HyperText Markup Language)
+ * - EPUB (E-book format)
  *
  * **Usage:**
  * ```typescript
@@ -66,6 +67,7 @@ export declare class OfficeParser {
      * - `.csv` → CsvParser
      * - `.md` → MarkdownParser
      * - `.html` → HtmlParser
+     * - `.epub` → EpubParser
      *
      * @param file - File path (string), Buffer, or ArrayBuffer containing the document
      * @param config - Optional configuration object (defaults applied for all omitted options)

package/dist/OfficeParser.js

@@ -15,6 +15,7 @@
  * - CSV (Comma-Separated Values)
  * - MD (Markdown)
  * - HTML (HyperText Markup Language)
+ * - EPUB (E-book format)
  *
  * **Usage:**
  * ```typescript
@@ -39,6 +40,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfficeParser = void 0;
 const CsvParser_js_1 = require("./parsers/CsvParser.js");
+const EpubParser_js_1 = require("./parsers/EpubParser.js");
 const ExcelParser_js_1 = require("./parsers/ExcelParser.js");
 const HtmlParser_js_1 = require("./parsers/HtmlParser.js");
 const MarkdownParser_js_1 = require("./parsers/MarkdownParser.js");
@@ -83,6 +85,7 @@ class OfficeParser {
      * - `.csv` → CsvParser
      * - `.md` → MarkdownParser
      * - `.html` → HtmlParser
+     * - `.epub` → EpubParser
      *
      * @param file - File path (string), Buffer, or ArrayBuffer containing the document
      * @param config - Optional configuration object (defaults applied for all omitted options)
@@ -232,6 +235,9 @@ class OfficeParser {
                 case 'md':
                     result = await (0, MarkdownParser_js_1.parseMarkdown)(buffer, internalConfig);
                     break;
+                case 'epub':
+                    result = await (0, EpubParser_js_1.parseEpub)(buffer, internalConfig);
+                    break;
                 default:
                     throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.EXTENSION_UNSUPPORTED, internalConfig, ext);
             }

package/dist/cli.d.ts

@@ -8,7 +8,7 @@
  *   officeparser file.docx --ocr --extractAttachments
  *
  * Options (--key=value, --key value, or bare flags):
- *   --to=json|text|md|html|csv|rtf|pdf|chunks  Convert AST to specified format (default: json)
+ *   --to=json|text|md|html|csv|rtf|pdf|epub|chunks  Convert AST to specified format (default: json)
  *   --output=path             Save result to a file
  *   --fileType=docx|xlsx|...  Override file type detection
  *   --ocr                     Enable OCR for images (default: false)

package/dist/cli.js

@@ -9,7 +9,7 @@
  *   officeparser file.docx --ocr --extractAttachments
  *
  * Options (--key=value, --key value, or bare flags):
- *   --to=json|text|md|html|csv|rtf|pdf|chunks  Convert AST to specified format (default: json)
+ *   --to=json|text|md|html|csv|rtf|pdf|epub|chunks  Convert AST to specified format (default: json)
  *   --output=path             Save result to a file
  *   --fileType=docx|xlsx|...  Override file type detection
  *   --ocr                     Enable OCR for images (default: false)
@@ -333,7 +333,7 @@ else {
     console.log('Usage: officeparser <file> [options]');
     console.log('');
     console.log('Options:');
-    console.log('  --to=json|text|md|html|pdf|csv|rtf|chunks   Target conversion format (default: json)');
+    console.log('  --to=json|text|md|html|pdf|csv|rtf|epub|chunks  Target conversion format (default: json)');
     console.log('  --output=file.ext                           Save output to file instead of stdout');
     console.log('  --fileType=docx|xlsx|pptx|odt|...           Explicitly override input file type detection');
     console.log('  --ocr                                       Enable OCR for images (default: false)');
@@ -360,6 +360,8 @@ else {
     console.log('Advanced Nested Config Examples:');
     console.log('  --pdfConfig.format=Letter                   Configure Puppeteer PDF format (A4 | Letter | Legal etc.)');
     console.log('  --chunksConfig.strategy=fixed-size          Chunking strategy (fixed-size | document-structure | semantic)');
+    console.log('  --mdConfig.dialect=github                   Markdown dialect (extended | github | gitlab | obsidian | pandoc | commonmark)');
+    console.log('  --mdConfig.fallbackToHtml=false              Disable HTML fallback for unsupported Markdown features (default: true)');
     console.log('');
     console.log('Format Syntax:');
     console.log('  Flags can be written as --flag (presence implies true), --no-flag (negation),');
@@ -371,5 +373,6 @@ else {
     console.log('  officeparser document.docx --to md');
     console.log('  officeparser report.pdf --ocr --ocrConfig.language eng --to text');
     console.log('  officeparser data.xlsx --to csv --output data.csv --csvDelimiter ";"');
+    console.log('  officeparser document.docx --extractAttachments --to epub --output document.epub');
     console.log('  officeparser image_doc --fileType docx --to json');
 }

package/dist/defaults.js

@@ -34,6 +34,13 @@ const DEFAULT_OCR_CONFIG = {
     autoTerminateTimeout: DEFAULT_OCR_TIMEOUT.autoTerminate,
     abortSignal: null,
 };
+/**
+ * Default configuration for HTML/XHTML parsing. `preserveAttributes` is off so that the AST is
+ * byte-identical to previous releases unless a caller opts in - see `HtmlParserConfig`.
+ */
+const DEFAULT_HTML_PARSER_CONFIG = {
+    preserveAttributes: false,
+};
 /**
  * Default configuration for the OfficeParser.
  */
@@ -62,7 +69,9 @@ exports.DEFAULT_OFFICE_PARSER_CONFIG = {
     decompressionLimits: {
         maxUncompressedBytes: 512 * 1024 * 1024,
         maxZipEntries: 10000,
+        maxTableCells: 1000000,
     },
+    htmlParserConfig: DEFAULT_HTML_PARSER_CONFIG,
 };
 /**
  * Default configuration for HTML generation.
@@ -117,6 +126,7 @@ const DEFAULT_CSV_GENERATOR_CONFIG = {
  */
 const DEFAULT_MD_GENERATOR_CONFIG = {
     fallbackToHtml: true,
+    dialect: 'extended',
 };
 /**
  * Default configuration for plain text generation.
@@ -124,6 +134,7 @@ const DEFAULT_MD_GENERATOR_CONFIG = {
 const DEFAULT_TEXT_GENERATOR_CONFIG = {
     newlineDelimiter: '\n',
     preserveLayout: true,
+    renderNotes: true,
 };
 /**
  * Default configuration for Fixed-Size chunking.
@@ -187,6 +198,7 @@ exports.DEFAULT_GENERATOR_CONFIG = {
     includeFormatting: true,
     generateIds: true,
     renderMetadata: false,
+    metadataOverrides: {},
     ignoreDefaultStyleMap: false,
     includeImages: true,
     includeCharts: true,