officeparser 6.1.0 → 7.0.0

package/README.md

@@ -1,6 +1,6 @@
-# officeParser 📄🚀
+# officeParser 📄🚀 - The Most Versatile Office Parser & Generator
 
-A robust, strictly-typed Node.js and Browser library for parsing office files ([`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)). It produces a clean, hierarchical Abstract Syntax Tree (AST) with rich metadata, text formatting, and full attachment support.
+A robust, strictly-typed Node.js and Browser library for parsing and generating office files. It not only extracts content from [`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), and [`html`](https://en.wikipedia.org/wiki/HTML) into a rich Abstract Syntax Tree (AST), but also provides a powerful generation engine to convert that AST into formats like **Markdown**, **HTML**, **CSV**, **RTF**, **Text**, **PDF**, and **JSON**, including native **RAG-focused chunking** support.
 
 [![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)
@@ -18,49 +18,15 @@ A robust, strictly-typed Node.js and Browser library for parsing office files ([
 - **Debugging**: Use the visualizer to debug parsing issues by inspecting exactly how nodes are interpreted.
 - **Format Specs**: Read detailed specifications for the AST structure and configuration options.
 
-*(Legacy Visualizer: If you prefer the [old simple visualizer](https://harshankur.github.io/officeParser/visualizer_old.html), it is still available.)*
+---
+
 
 ---
 
+### 📝 [Changelog](CHANGELOG.md)
+*Detailed release notes and the full history of updates are available in the project changelog.*
 
-#### Update
-* 2026-04-14 - **v6.1.0 Release**: Major Infrastructure & Resource Stability. (Incremental since v6.0.0)
-    - **OCR Scheduler**: Intelligent worker pool that optimizes Tesseract lifecycle across parallel requests. **Note**: By default, Node.js processes stay active for 10s after OCR to keep workers warm (configurable via `ocrConfig.autoTerminateTimeout`); use `terminateOcr()` for immediate CLI/script exit.
-    - **Core Engine**: Replaced legacy zip extraction with `fflate` for significant performance gains and robust browser/edge compatibility.
-    - **Module System**: Full native ESM support with `Node16` resolution and verified browser bundles (Vite/Angular compatible).
-    - **Format Refinements**: Hierarchical PDF coordinate alignment and ODT/RTF list parsing stability.
-    - **Custom Properties**: Added support for extracting custom document metadata across OOXML, ODF, and PDF formats.
-    - **Sponsorship**: Integrated `funding.json` manifest and GitHub Sponsors support.
-* 2025/12/29 - **v6.0.0 Release**: Major overhaul of the library. Transitioned from simple text extraction to a rich **Abstract Syntax Tree (AST)** output.
-    - Simplified API: Use `parseOffice` for all parsing needs (returns a Promise).
-    - Structured Output: Access hierarchical document structure (paragraphs, headings, tables, lists, etc.).
-    - Rich Metadata: Extracted document properties (author, title, creation date).
-    - Enhanced Formatting: Support for bold, italic, colors, fonts, alignment, etc.
-    - Attachment Handling: Extract images, charts, and embedded files as Base64.
-    - OCR Integration: Optional OCR for images using Tesseract.js.
-    - RTF Support: Added full support for Rich Text Format files.
-    - Improved Type Definitions: Full TypeScript support with detailed interfaces.
-* 2024/11/12 - Added ArrayBuffer as a type of file input. Generating bundle files now which exposes namespace officeParser to be able to access parseOffice directly on the browser.
-* 2024/10/21 - Replaced extracting zip files from decompress to yauzl. This means that we now extract files in memory and we no longer need to write them to disk. Removed config flags related to extracted files. Added flags for CLI execution.
-* 2024/10/15 - Fixed erroring out while deleting temp files when multiple worker threads make parallel executions resulting in same file name for multiple files. Fixed erroring out when multiple executions are made without waiting for the previous execution to finish which resulted in deleting the file from other execution. Upgraded dependencies.
-* 2024/10/13 - Fixed parsing text from xlsx files which contain no shared strings file and files which have inlineStr based strings.
-* 2024/05/06 - Replaced pdf parsing support from pdf-parse library to natively building it using pdf.js library from Mozilla by analyzing its output. Added pdfjs-dist build as a local library.
-* 2023/11/25 - Fixed error catching when an error occurs within the parsing of a file, especially after decompressing it. Also fixed the problem with parallel parsing of files as we were using only timestamp in file names.
-* 2023/10/24 - Revamped content parsing code. Fixed order of content in files, especially in word files where table information would always land up at the end of the text. Added config object as argument for parseOffice which can be used to set new line delimiter and multiple other configurations. Added support for parsing pdf files using the popular npm library pdf-parse. Removed support for individual file parsing functions.
-* 2023/04/26 - Added support for file buffers as argument for filepath for parseOffice and parseOfficeAsync
-* 2023/04/07 - Added typings to methods to help with Typescript projects.
-* 2022/12/28 - Added command line method to use officeParser with or without installing it and instantly get parsed content on the console.
-* 2022/12/10 - Fixed memory leak issues, bugs related to parsing open document files and improved error handling.
-* 2021/11/21 - Added promise way to existing callback functions.
-* 2020/06/01 - Added error handling and console.log enable/disable methods. Default is set at enabled. Everything backward compatible.
-* 2019/06/17 - Added method to change location for decompressing office files in places with restricted write access.
-* 2019/04/30 - Removed case sensitive file extension bug. File names with capital lettered extensions now supported.
-* 2019/04/23 - Added support for open office files *.odt, *.odp, *.ods through parseOffice function. Created a new method parseOpenOffice for those who prefer targetted functions. 
-* 2019/04/23 - Added feature to delete the generated dist folder after function callback.
-* 2019/04/22 - Added parseOffice method to avoid confusion between type of file and their extension.
-* 2019/04/22 - Added file extension validations. Removed errors for excel files with no drawing elements.
-* 2019/04/19 - Support added for *.xlsx files.
-* 2019/04/18 - Support added for *.pptx files.
+---
 
 ## Install via npm
 
@@ -69,7 +35,7 @@ npm i officeparser
 ```
 
 ## Command Line usage
-You can use `officeparser` directly from the terminal to get either the full AST (as JSON) or plain text.
+You can use `officeparser` directly from the terminal to extract content as JSON AST, plain text, or generate new formats like Markdown and HTML.
 
 ```bash
 # Get full AST as JSON (default)
@@ -78,24 +44,33 @@ npx officeparser /path/to/officeFile.docx
 # Get plain text only
 npx officeparser /path/to/officeFile.docx --toText=true
 
-# Use configuration options
-npx officeparser /path/to/officeFile.docx --ignoreNotes=true --newlineDelimiter=" "
+# Generate Markdown file
+npx officeparser report.docx --format=md --output=report.md
+
+# Generate HTML file with specific output
+npx officeparser presentation.pptx --format=html --output=preview.html
+
+# Convert spreadsheet to CSV
+npx officeparser data.xlsx --format=csv
 ```
 
 ### Config Options:
-- `--toText=[true|false]`              Flag to output only plain text instead of JSON AST.
+- `--format=[json|text|md|html|csv|rtf|pdf|chunks]` The output format. Default is `json`.
+- `--output=[path]`                    Optional file path to write the output to.
+- `--toText=[true|false]`              Legacy flag to output only plain text. Use `--format=text` instead.
 - `--ignoreNotes=[true|false]`          Flag to ignore notes from files like PowerPoint. Default is false.
 - `--newlineDelimiter=[delimiter]`      The delimiter to use for new lines. Default is `\n`.
 - `--putNotesAtLast=[true|false]`       Flag to collect notes at the end of files like PowerPoint. Default is false.
-- `--outputErrorToConsole=[true|false]` Flag to output errors to the console. Default is false.
+- `--outputErrorToConsole=[true|false]` **(Deprecated)** Flag to output errors to the console. Use `onWarning` callback in library usage.
 - `--extractAttachments=[true|false]`   Flag to extract images/charts as Base64. Default is false.
 - `--ocr=[true|false]`                  Flag to enable OCR for extracted images. Default is false.
 - `--includeRawContent=[true|false]`    Flag to include raw XML/RTF content in nodes. Default is false.
+- `--includeBreakNodes=[true|false]`    Flag to include break nodes. Currently only available for DOCX documents.
 - `--verbose=[true|false]`              Show full error stack traces.
 
 
 ## Library Usage
-In **v6.0.0**, the library has moved to a structured AST output. While this is a change for those expecting a string directly, it provides significantly more power and flexibility.
+In **v7.0.0**, the library has evolved into a dual-purpose **Parser** and **Generator**. You can first parse any office file into a structured AST and then use the `OfficeGenerator` to transform that AST into various formats or chunks.
 
 ### Getting Started (Async/Await)
 ```js
@@ -130,8 +105,103 @@ const text = await getText("/path/to/officeFile.docx");
 console.log(text);
 ```
 
+## Using the OfficeGenerator
+The `OfficeGenerator` is a powerful tool to convert your AST into human-readable formats or structured data.
+
+```typescript
+import { OfficeParser, OfficeGenerator } from 'officeparser';
+
+const ast = await OfficeParser.parseOffice('report.docx');
+
+// 1. Convert to Markdown
+const md = await OfficeGenerator.generate(ast, 'md');
+console.log(md.value);
+
+// 2. Convert to HTML with structured style mapping (Recommended)
+const html = await OfficeGenerator.generate(ast, 'html', {
+    includeFormatting: true,
+    styleMap: [
+        { 
+            selector: { nodeType: 'paragraph', attributes: { style: 'Heading 1' } }, 
+            output: { tag: 'h1', classes: ['main-title'] } 
+        }
+    ]
+});
+console.log(html.value);
+
+// 3. Convert to CSV (for spreadsheets)
+const csv = await OfficeGenerator.generate(ast, 'csv');
+console.log(csv.value);
+```
+
+## The New "One-Step" API: `OfficeConverter`
+In **v7.0.0**, we introduced the `OfficeConverter.convert` method. This is the new high-level API designed for one-step transformations where you don't need to manually interact with the AST. It automatically handles parser and generator configuration synchronization.
+
+```typescript
+import { OfficeConverter } from 'officeparser';
+
+// One-step conversion from DOCX to Markdown
+const result = await OfficeConverter.convert('report.docx', 'md');
+console.log(result.value); // The generated Markdown string
+console.log(result.messages); // Array of warnings/info (e.g., "Skipped unsupported drawing")
+
+// Complex conversion with nested configuration
+const htmlResult = await OfficeConverter.convert('data.xlsx', 'html', {
+    parseConfig: { 
+        ignoreNotes: true 
+    },
+    generatorConfig: {
+        includeFormatting: true,
+        styleMap: [
+            { 
+                selector: { attributes: { style: { value: 'Header', operator: '~=' } } }, 
+                output: { tag: 'h2', classes: ['data-header'] } 
+            }
+        ]
+    },
+    onWarning: (msg) => console.warn("Conversion Warning:", msg)
+});
+```
+
+## Native RAG Chunking
+`officeParser` provides native support for document chunking, specifically designed for Retrieval-Augmented Generation (RAG) workflows. It offers three distinct strategies to split your documents while maintaining context and metadata.
+
+### 1. Fixed-Size Strategy (Recursive)
+Splits text into chunks based on character count with a specified overlap. It uses smart boundary detection to avoid cutting in the middle of sentences or paragraphs.
+
+### 2. Document Structure Strategy
+Splits the document at natural structural boundaries like pages (PDF/Word), slides (PPTX), or high-level headings. This preserves the logical flow of the document.
+
+### 3. Semantic Strategy
+Uses cosine similarity between sentence embeddings to identify coherent topic boundaries. This ensures that each chunk contains semantically related content (requires an embedding function).
+
+### The `OfficeChunk` Interface
+Every chunk produced contains not just text, but rich metadata to help your RAG pipeline:
+```typescript
+{
+  text: string;           // The chunk content
+  metadata: {
+    sourceType: string;   // e.g., "docx", "pdf"
+    pageNumber?: number;  // Current page
+    slideNumber?: number; // Current slide
+    closestHeading?: string; // The heading this chunk belongs to
+    chunkIndex: number;   // Sequential index
+  }
+}
+```
+
+#### Example: Generating Chunks
+```typescript
+const chunks = await OfficeGenerator.generate(ast, 'chunks', {
+    strategy: 'fixed-size',
+    maxChunkSize: 1000,
+    chunkOverlap: 200
+});
+console.log(`Generated ${chunks.value.length} chunks`);
+```
+
 ### Using Callbacks (Backward Compatibility Support)
-We still support callbacks, but the data returned is now the AST object.
+Callbacks are still supported for those preferred, but the data returned is now the AST object.
 ```js
 const officeParser = require('officeparser');
 
@@ -165,14 +235,14 @@ The `OfficeParserAST` provides a format-agnostic representation of your document
 
 ```text
 OfficeParserAST
-├── type: "docx" | "pptx" | "xlsx" | ...
+├── type: "docx" | "pdf" | "xlsx" | "csv" | "md" | ... (11 formats supported)
 ├── metadata: { author, title, created, modified, ..., customProperties }
 ├── content: [ OfficeContentNode ]
 │   ├── type: "paragraph" | "heading" | "table" | "list" | ...
 │   ├── text: "Concatenated text of this node and all children"
 │   ├── children: [ OfficeContentNode ] (recursive)
 │   ├── formatting: { bold, italic, color, size, font, ... }
-│   ├── metadata: { level, listId, row, col, ... }
+│   ├── metadata: { level, listId, paragraphIndentation, row, col, ... }
 │   └── rawContent: "<xml>...</xml>" (if enabled)
 ├── attachments: [ OfficeAttachment ]
 │   ├── type: "image" | "chart"
@@ -224,13 +294,15 @@ List Node
     listId: "1", 
     listType: "ordered", 
     indentation: 0, 
+    paragraphIndentation: { left: 720, hanging: 360 },
     itemIndex: 0 
 }
 └── children: [ Text Content... ]
 ```
 
 - **`listId`**: A unique identifier for the list definition. Multiple items with the same `listId` belong to the same logical list.
-- **`indentation`**: The nesting level (0-based).
+- **`indentation`**: The structural nesting level (0-based).
+- **`paragraphIndentation`**: The physical indentation formatting in twentieths of a point (twips) (e.g., `left`, `right`, `firstLine`, `hanging`).
 - **`itemIndex`**: The sequential position within that list level.
 - **`listType`**: Either `ordered` (numbered) or `unordered` (bulleted).
 
@@ -309,13 +381,31 @@ Formatting can be found at two levels:
 1.  **Node Level**: Applied directly to a text run or paragraph.
 2.  **Document Level**: Found in `ast.metadata.formatting` (defaults) or `ast.metadata.styleMap` (named styles).
 
-### 6. Advanced Metadata
+### 6. Breaks
+Breaks are currently only supported when parsing DOCX-documents. Breaks are added as a node of type `break` and carry metadata of the type `BreakMetadata`. When `includeRawContent` is enabled, they also include the `rawContent` string from the original XML.
+
+```text
+Break Node
+├── type: "break"
+└── metadata: {
+        breakType: "textWrapping" | "page" | "column" | "lastRenderedPage" | "carriageReturn",
+        clear?: "all" | "left" | "none" | "right"
+    }
+```
+
+- `breakType`: Type of break. `textWrapping` (default) is a standard line break, `page` is a page break, `column` is a break to the next column, `lastRenderedPage` is a soft break inserted by Word, and `carriageReturn` is an explicit carriage return (`w:cr`).
+- `clear`: Relevant for `textWrapping`. Indicates if text should wrap around floating objects.
+
+> [!NOTE]
+> Even though break nodes don't have a `text` property, the `ast.toText()` method will automatically convert them to newlines (`\n`) or the configured delimiter in the final string output.
+
+### 7. Advanced Metadata
 The `ast.metadata` object provides document-wide context:
 - **`styleMap`**: A dictionary of style names to their `TextFormatting` definitions found in the document.
 - **`formatting`**: Document-wide default settings (e.g., default font or font size).
 - **`customProperties`**: A dictionary of user-defined metadata embedded in the document (OOXML `custom.xml`, ODF `meta:user-defined`, or PDF Info dictionary).
 
-### 7. Custom Properties
+### 8. Custom Properties
 You can access custom user-defined metadata that might be embedded in the document:
 
 ```javascript
@@ -324,6 +414,14 @@ console.log("Custom Metadata:", ast.metadata.customProperties);
 // Output: { "ProjectID": "ABC-123", "InternalReview": true }
 ```
 
+## Performance & Fidelity Highlights (v7.0.0)
+The v7.0.0 release brings significant internal optimizations and fidelity improvements:
+- **OpenOffice Speedups**: Up to **23x faster** parsing for ODP presentations thanks to optimized XML caching.
+- **Excel Memory Efficiency**: Resolved $O(n)$ memory overhead issues for large spreadsheets (#91) by switching to iterative stream-based parsing.
+- **RTF Performance**: Rewritten core loop to resolve $O(n^2)$ bottlenecks during string accumulation.
+- **Advanced Table Fidelity**: Native support for **vertical cell merging** (`vMerge`) and **horizontal spanning** (`gridSpan`) in DOCX, ensuring complex tables look exactly as they do in Word.
+- **Parser Extensions**: You can now parse `CSV`, `Markdown`, and `HTML` files *into* the unified Office AST, allowing you to use the `OfficeGenerator` on them just like any other format.
+
 ### Advanced AST Usage
 Beyond using `ast.toText()`, you can interact with the structural data directly:
 
@@ -418,29 +516,114 @@ Pass an optional config object as the second argument to `parseOffice`.
 
 | Flag | DataType | Default | Explanation |
 |------|----------|---------|-------------|
-| `outputErrorToConsole` | boolean | `false` | Show logs to console in case of an error. |
+| `outputErrorToConsole` | boolean | `false` | **Deprecated**: Use `onWarning` instead. Show logs to console in case of an error. |
 | `newlineDelimiter` | string | `\n` | Delimiter for new lines in text output. |
 | `ignoreNotes` | boolean | `false` | Ignore notes in files like PowerPoint/ODP. |
-| `putNotesAtLast` | boolean | `false` | Put notes text at the end of the document. (Note: Does not work for RTF. It is treated as true always.) |
+| `putNotesAtLast` | boolean | `false` | Put notes text at the end of the document. |
 | `extractAttachments` | boolean | `false` | Extract images and charts as Base64. |
 | `includeRawContent` | boolean | `false` | Include raw XML/RTF markup in the nodes. |
-| `serializeRawContent` | boolean | `true` | When `includeRawContent` is true, re-serializes raw XML to clean strings. If false, extracts original raw substring. |
-| `preserveXmlWhitespace` | boolean | `false` | When `serializeRawContent` is true, preserves original XML whitespace and line endings. |
+| `serializeRawContent` | boolean | `true` | Re-serializes raw XML to clean strings. |
+| `preserveXmlWhitespace` | boolean | `false` | Preserves original XML whitespace. |
 | `ocr` | boolean | `false` | Enable OCR for images (requires `extractAttachments: true`). |
-| `ocrLanguage` | string | `eng` | **Deprecated**: Use `ocrConfig.language` instead. Language for OCR. |
-| `pdfWorkerSrc` | string | `(see below)` | Path to PDF.js worker. Defaults to a CDN link if not provided. |
-| `ocrConfig` | object | `{}` | **OCR Scheduler** configuration for fine-grained worker control. |
-| `ocrConfig.language` | string | `eng` | Language(s) for OCR (e.g., 'eng', 'fra', 'eng+fra'). |
-| `ocrConfig.autoTerminateTimeout` | number | `10000` | Inactivity timeout in milliseconds before workers are killed. |
-| `ocrConfig.workerPath` | string | `undefined` | Path to Tesseract worker script (for offline use). |
-| `ocrConfig.corePath` | string | `undefined` | Path to Tesseract core script (for offline use). |
-| `ocrConfig.langPath` | string | `undefined` | Path for Tesseract language files (for offline use). |
+| `pdfWorkerSrc` | string | `(see below)` | Path to PDF.js worker. |
+| `ocrConfig` | object | `{}` | OCR Scheduler configuration. |
+| `includeBreakNodes` | boolean | `false` | Include `w:br`, `w:cr` nodes (DOCX only).|
+| `ignoreInternalLinks` | boolean | `false` | Remove all bookmarks and internal jumps. |
+| `csvDelimiter` | string | `,` | Custom delimiter for parsing CSV files. |
+| `fileType` | string | `null` | Manual format override (authoritative). |
+
+## Generator Configuration: GeneratorConfig
+Configuration options for `OfficeGenerator.generate`.
+
+| Flag | DataType | Default | Explanation |
+|------|----------|---------|-------------|
+| `includeFormatting` | boolean | `false` | Whether to include semantic styles (bold, italic) in output. |
+| `styleMap` | string[] \| array | `[]` | Array of style mappings (DSL strings or structured objects). |
+| `ignoreDefaultStyleMap`| boolean | `false` | Ignore the library's default style mappings. |
+| `includeMetadata` | boolean | `false` | Include document metadata in the output (e.g., as frontmatter). |
+| `onNode` | function | `undefined` | Callback to intercept/modify any node during generation. |
+
+### 🛠️ Advanced Node Manipulation (Pro Users)
+The `onNode` callback is a powerful tool that gives you complete control over the generation process. It is called for **every single node** in the AST before it is rendered.
+
+#### Callback Capabilities:
+1.  **Filter/Remove Nodes**: Return `false` to skip a node and all its children.
+2.  **Override Rendering**: Return a `string` to use that exact text as the output, bypassing default logic and recursion.
+3.  **Mutate Nodes**: Modify the `node` object directly (e.g., changing `node.text`) and return `void` to let the generator proceed with your changes.
+4.  **Async Support**: The callback can be `async`, allowing you to fetch external data or perform complex logic during generation.
+
+#### Pro Example:
+```typescript
+const result = await ast.to('md', {
+    onNode: async (node) => {
+        // 1. Skip all images
+        if (node.type === 'image') return false;
+
+        // 2. Redact sensitive info by mutating the node
+        if (node.text?.includes('SECRET_KEY')) {
+            node.text = node.text.replace(/SECRET_KEY: \w+/, 'SECRET_KEY: [REDACTED]');
+        }
+
+        // 3. Custom rendering for specific styles
+        if (node.metadata?.style === 'Callout') {
+            return `> [!INFO]\n> ${node.text}`;
+        }
+
+        // 4. Proceed with default rendering (implicitly returns void)
+    }
+});
+```
+
+### Advanced Style Mapping (Semantic Translation)
+The `styleMap` configuration is the primary way to define the "semantic meaning" of document styles. We recommend using **Structured Style Mappings** for full type safety and power.
+
+#### 1. Structured Style Mappings (Recommended)
+Use structured objects to match nodes based on type and attributes, and specify detailed output properties like classes and custom attributes.
+
+```typescript
+styleMap: [
+    { 
+        selector: { 
+            nodeType: 'paragraph', 
+            attributes: { style: 'Heading 1' } 
+        }, 
+        output: { 
+            tag: 'h1', 
+            classes: ['main-title'], 
+            attributes: { id: 'top' } 
+        } 
+    },
+    {
+        // Use operators like '~=' for partial matches
+        selector: { attributes: { style: { value: 'Quote', operator: '~=' } } },
+        output: { tag: 'blockquote' }
+    }
+]
+```
+
+#### 2. Legacy String DSL
+The library also maintains support for a simple string-based DSL, highly compatible with `mammoth.js`.
+
+- **Literal Matching**: `"p[style-name='Heading 1'] => h1"`
+- **Regex-like Matching**: `"p[style~='Title'] => h2"`
+- **Attribute Filters**: `"p[style-name='Quote'][lang='en'] => blockquote"`
+
+## Chunking Configuration: ChunkingConfig
+Specific options when using `format: 'chunks'`.
+
+| Flag | DataType | Default | Explanation |
+|------|----------|---------|-------------|
+| `strategy` | string | `'fixed-size'`| The chunking strategy (`fixed-size`, `document-structure`, `semantic`). |
+| `maxChunkSize` | number | `1000` | Maximum characters per chunk. |
+| `chunkOverlap` | number | `200` | Overlap between consecutive chunks. |
+| `similarityThreshold`| number | `0.5` | Threshold for semantic splitting (0.0 to 1.0). |
+| `embedBatchSize` | number | `50` | Batch size for embedding requests. |
 
 ### OCR Scheduler & Resource Management
 If your application uses OCR, `officeParser` utilizes an intelligent **Smart Worker Pool** to maintain a background worker pool and optimize repeated parse requests.
 
 - **Dynamic Affinity**: Workers in the pool persist with their last used language affinity. 
-- **Smart Re-initialization**: If a new language is requested and the pool is full, the manager identifies the **Least Recently Used (LRU)** idle worker and re-initializes it for the new language using the Tesseract.js v5 API. This avoids the overhead of destroying and recreating workers.
+- **LRU Re-allocation**: If a new language is requested and the pool is full, the manager identifies the **Least Recently Used (LRU)** idle worker and re-initializes it for the new language. This avoids the overhead of destroying and recreating workers.
 - **Auto-Termination**: Workers are automatically cleaned up after 10 seconds of inactivity (configurable via `ocrConfig.autoTerminateTimeout`).
 
 #### `OfficeParser.terminateOcr()`
@@ -462,7 +645,7 @@ async function runCleaner() {
 ```
 
 > [!TIP]
-> This is handled automatically in our own CLI (`npx officeparser ...`). You only need to call this manually if you are using the library in your own custom script and want a snappy exit.
+> This is handled automatically in the built-in CLI (`npx officeparser ...`). You only need to call this manually if you are using the library in your own custom script and want a snappy exit.
 
 ```js
 const config = {
@@ -509,36 +692,51 @@ The library provides two types of browser bundles in the `dist/` directory:
 1. **`officeparser.browser.iife.js`**: Standard IIFE bundle for direct `<script>` tag usage. Exposes the global `officeParser` namespace.
 2. **`officeparser.browser.mjs`**: Modern ESM bundle for use with `import` statements or modern bundlers.
 
+### Usage (ESM)
+If you are using a modern bundler like **Vite**, **Webpack**, or **Next.js**:
+
+```javascript
+import { OfficeParser } from 'officeparser';
+
+const handleFile = async (event) => {
+    const file = event.target.files[0];
+    const buffer = await file.arrayBuffer();
+    
+    try {
+        // Pass the Buffer or Uint8Array directly
+        const ast = await OfficeParser.parseOffice(new Uint8Array(buffer));
+        console.log(ast.toText());
+    } catch (err) {
+        console.error(err);
+    }
+};
+```
+
+> [!NOTE] 
+> **Why `fs` fails in the browser**: Browsers do not have a built-in file system. If you try to pass a file path string in the browser, `officeParser` will throw a descriptive "Fail-Fast" error instead of crashing mysteriously: 
+> `[officeparser] Node.js 'fs' module is not available in the browser. Please pass a Buffer or Uint8Array instead.`
+
 ### Usage (Script Tag)
-Include the IIFE bundle file available in the release assets.
+Include the IIFE bundle available in the release assets or your `dist/` folder. This exposes the global `officeParser` object.
 
 ```html
 <script src="dist/officeparser.browser.iife.js"></script>
 <script>
-    async function handleFile(file) {
-        // file can be a File object from an input element or an ArrayBuffer
+    async function handleFile(event) {
+        const file = event.target.files[0];
+        const buffer = await file.arrayBuffer();
+        
         try {
-            const ast = await officeParser.parseOffice(file, { ocr: true });
+            // Reconstruct as Uint8Array for the parser
+            const ast = await officeParser.parseOffice(new Uint8Array(buffer));
             console.log(ast.toText());
         } catch (error) {
-            console.error(error);
+            console.error("Parsing failed:", error);
         }
     }
 </script>
 ```
 
-### Usage (ESM)
-If you are using a modern browser that supports modules or a dev server like Vite:
-
-```html
-<script type="module">
-    import { OfficeParser } from './dist/officeparser.browser.mjs';
-    
-    const ast = await OfficeParser.parseOffice(fileBuffer);
-    console.log(ast.metadata);
-</script>
-```
-
 ### PDF Worker Configuration in Browser
 When using `officeparser` in a browser environment to parse PDF files, you may provide the `pdfWorkerSrc` configuration option. If not provided, it defaults to a CDN link for `pdfjs-dist@5.6.205`.
 
@@ -550,7 +748,7 @@ const ast = await officeParser.parseOffice(file);
 
 // Or override it with your own path or a different version:
 const ast2 = await officeParser.parseOffice(file, {
-    pdfWorkerSrc: "https://unpkg.com/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs"
+    pdfWorkerSrc: "https://cdn.jsdelivr.net/npm/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs"
 });
 ```
 
@@ -579,7 +777,7 @@ For a comprehensive guide, visit our [Debugging & Troubleshooting Documentation]
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
 
 ## License
 

package/dist/OfficeConverter.d.ts

@@ -0,0 +1,46 @@
+import { ConversionResult, OfficeConverterConfig, SupportedDestination, SupportedFileType } from './types.js';
+/**
+ * Utility type to infer the file type from a file path string literal.
+ */
+type InferFileTypeFromPath<T> = T extends `${string}.${infer E}` ? (Lowercase<E> extends SupportedFileType ? Lowercase<E> : SupportedFileType) : SupportedFileType;
+/**
+ * Main converter class providing a streamlined one-step API for document conversion.
+ *
+ * This class coordinates the `OfficeParser` and `OfficeGenerator` to transform
+ * documents from one format to another (e.g., DOCX to Markdown, PDF to HTML).
+ */
+export declare class OfficeConverter {
+    /**
+     * Converts an office document from its source format to a specified destination format.
+     *
+     * This method:
+     * 1. Detects the source file type and parses it into a unified AST using `OfficeParser`.
+     * 2. Automatically configures the parser based on the generator requirements (e.g., enabling
+     *    attachment extraction if images are requested in the output).
+     * 3. Generates the destination document from the AST using `OfficeGenerator`.
+     *
+     * @template F The inferred type of the input file (path string or buffer).
+     * @template T The authoritative source file type (inferred from path or config).
+     *
+     * @param file - File path (string), Buffer, or ArrayBuffer containing the source document.
+     * @param destination - The target format (e.g., 'md', 'html', 'pdf', 'text', 'chunks').
+     * @param config - Optional unified configuration for both the parser and generator phases.
+     *
+     * @returns A promise resolving to the ConversionResult containing the value and messages.
+     * @throws {Error} If the source format is unsupported or parsing/generation fails.
+     *
+     * @example
+     * ```typescript
+     * // Convert Word to Markdown with a single call
+     * const { value: markdown } = await OfficeConverter.convert('report.docx', 'md');
+     *
+     * // Convert PDF to HTML with OCR enabled for images
+     * const { value: html } = await OfficeConverter.convert(buffer, 'html', {
+     *   ocr: true,
+     *   includeImages: true
+     * });
+     * ```
+     */
+    static convert<F extends string | Buffer | ArrayBuffer, T extends SupportedFileType = InferFileTypeFromPath<F>>(file: F, destination: SupportedDestination<T>, config?: OfficeConverterConfig<SupportedDestination<T>, T>): Promise<ConversionResult<SupportedDestination<T>>>;
+}
+export {};

package/dist/OfficeConverter.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfficeConverter = void 0;
+const OfficeGenerator_js_1 = require("./OfficeGenerator.js");
+const OfficeParser_js_1 = require("./OfficeParser.js");
+/**
+ * Main converter class providing a streamlined one-step API for document conversion.
+ *
+ * This class coordinates the `OfficeParser` and `OfficeGenerator` to transform
+ * documents from one format to another (e.g., DOCX to Markdown, PDF to HTML).
+ */
+class OfficeConverter {
+    /**
+     * Converts an office document from its source format to a specified destination format.
+     *
+     * This method:
+     * 1. Detects the source file type and parses it into a unified AST using `OfficeParser`.
+     * 2. Automatically configures the parser based on the generator requirements (e.g., enabling
+     *    attachment extraction if images are requested in the output).
+     * 3. Generates the destination document from the AST using `OfficeGenerator`.
+     *
+     * @template F The inferred type of the input file (path string or buffer).
+     * @template T The authoritative source file type (inferred from path or config).
+     *
+     * @param file - File path (string), Buffer, or ArrayBuffer containing the source document.
+     * @param destination - The target format (e.g., 'md', 'html', 'pdf', 'text', 'chunks').
+     * @param config - Optional unified configuration for both the parser and generator phases.
+     *
+     * @returns A promise resolving to the ConversionResult containing the value and messages.
+     * @throws {Error} If the source format is unsupported or parsing/generation fails.
+     *
+     * @example
+     * ```typescript
+     * // Convert Word to Markdown with a single call
+     * const { value: markdown } = await OfficeConverter.convert('report.docx', 'md');
+     *
+     * // Convert PDF to HTML with OCR enabled for images
+     * const { value: html } = await OfficeConverter.convert(buffer, 'html', {
+     *   ocr: true,
+     *   includeImages: true
+     * });
+     * ```
+     */
+    static async convert(file, destination, config) {
+        // 1. Prepare Parser Configuration
+        // We prioritize the top-level onWarning if provided.
+        const parserConfig = {
+            ...config?.parseConfig,
+            onWarning: config?.onWarning || config?.parseConfig?.onWarning,
+        };
+        // Remove OCR settings for the streamlined converter as requested
+        parserConfig.ocr = false;
+        // Remove undefined keys to prevent overwriting defaults in resolveParserConfig
+        Object.keys(parserConfig).forEach((key) => parserConfig[key] === undefined && delete parserConfig[key]);
+        /**
+         * AUTOMATIC CONFIGURATION SYNC
+         * We sync extractAttachments from the generator configuration.
+         */
+        parserConfig.extractAttachments = (config?.generatorConfig?.includeImages !== false) || (config?.generatorConfig?.includeCharts !== false);
+        // 2. Parse the source document into the universal AST
+        const ast = await OfficeParser_js_1.OfficeParser.parseOffice(file, parserConfig);
+        // 3. Generate the destination document from the AST
+        const generatorConfig = {
+            ...config?.generatorConfig,
+            onWarning: config?.onWarning || config?.generatorConfig?.onWarning,
+        };
+        const result = await OfficeGenerator_js_1.OfficeGenerator.generate(ast, destination, generatorConfig);
+        result.messages = [...(ast.warnings || []), ...result.messages];
+        return result;
+    }
+}
+exports.OfficeConverter = OfficeConverter;