officeparser 6.0.7 → 6.1.1

package/README.md

@@ -3,6 +3,8 @@
 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.
 
 [![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)
+[![Weekly Downloads](https://img.shields.io/npm/dw/officeparser.svg)](https://www.npmjs.com/package/officeparser)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
@@ -21,37 +23,12 @@ A robust, strictly-typed Node.js and Browser library for parsing office files ([
 ---
 
 
-#### Update
-* 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.
+---
+
+### 📝 [Changelog](CHANGELOG.md)
+*Detailed release notes and the full history of updates are available in the project changelog.*
+
+---
 
 ## Install via npm
 
@@ -82,6 +59,8 @@ npx officeparser /path/to/officeFile.docx --ignoreNotes=true --newlineDelimiter=
 - `--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
@@ -121,7 +100,7 @@ console.log(text);
 ```
 
 ### 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');
 
@@ -156,13 +135,13 @@ The `OfficeParserAST` provides a format-agnostic representation of your document
 ```text
 OfficeParserAST
 ├── type: "docx" | "pptx" | "xlsx" | ...
-├── metadata: { author, title, created, modified, ... }
+├── 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"
@@ -177,7 +156,7 @@ OfficeParserAST
 ```json
 {
   "type": "docx",
-  "metadata": { "author": "John Doe", "title": "Annual Report" },
+  "metadata": { "author": "John Doe", "title": "Annual Report", "customProperties": { "Department": "Finance" } },
   "content": [
     {
       "type": "heading",
@@ -214,13 +193,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).
 
@@ -299,10 +280,38 @@ 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).
+
+### 8. Custom Properties
+You can access custom user-defined metadata that might be embedded in the document:
+
+```javascript
+const ast = await officeParser.parseOffice("contract.docx");
+console.log("Custom Metadata:", ast.metadata.customProperties);
+// Output: { "ProjectID": "ABC-123", "InternalReview": true }
+```
 
 ### Advanced AST Usage
 Beyond using `ast.toText()`, you can interact with the structural data directly:
@@ -403,10 +412,47 @@ Pass an optional config object as the second argument to `parseOffice`.
 | `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.) |
 | `extractAttachments` | boolean | `false` | Extract images and charts as Base64. |
-| `ocr` | boolean | `false` | Enable OCR for images (requires `extractAttachments: true`). |
-| `ocrLanguage` | string | `eng` | Language for OCR (e.g., 'eng', 'fra'). Supports multiple languages with '+'. See [Language Codes](https://tesseract-ocr.github.io/tessdoc/Data-Files#data-files-for-version-400-november-29-2016). |
 | `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. |
+| `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). |
+| `includeBreakNodes` | boolean | `false` | Specifically targets Word documents (DOCX). When set to true, officeParser will also parse `w:br`, `w:cr` and `w:lastRenderedPageBreak` nodes.|
+
+### 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. 
+- **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()`
+If you have used OCR (`{ ocr: true }`) in a short-lived script (like CLI tools or one-off automation), we recommend explicitly calling `terminateOcr()` after your processing is finished. This bypasses the 10-second idle timer and allows the process to return to the terminal prompt immediately.
+
+> [!NOTE]
+> If OCR was not used, this function is a no-op and does not need to be called.
+
+```js
+const officeParser = require('officeparser');
+
+async function runCleaner() {
+    await officeParser.parseOffice("file.pdf", { ocr: true });
+    // ... process results ...
+
+    // Manually kill OCR workers for an immediate exit
+    await officeParser.terminateOcr();
+}
+```
+
+> [!TIP]
+> 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 = {
@@ -449,29 +495,57 @@ officeParser.parseOffice("presentation.pptx", config).then(ast => {
 ```
 
 ## Browser Usage
-The browser bundle exposes the `officeParser` namespace. Include the bundle file available in the release assets.
+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 available in the release assets or your `dist/` folder. This exposes the global `officeParser` object.
 
 ```html
-<script src="dist/officeparser.browser.js"></script>
+<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
-        // The browser bundle exposes the global variable `officeParser`
-        // which contains the `OfficeParser` class.
+    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());
-            console.log("Metadata:", ast.metadata);
         } catch (error) {
-            console.error(error);
+            console.error("Parsing failed:", error);
         }
     }
 </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.5.207`.
+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`.
 
 ```javascript
 const file = ...; // File object or ArrayBuffer
@@ -481,11 +555,21 @@ 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.5.207/build/pdf.worker.min.mjs"
+    pdfWorkerSrc: "https://unpkg.com/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs"
 });
 ```
 
-> **Note:** The version of `pdfjs-dist` in the worker source should match the version used by `officeparser` (currently `5.4.530`).
+> **Note:** The version of `pdfjs-dist` in the worker source should match the version used by `officeparser` (currently `5.6.205`).
+
+## Troubleshooting & Common Issues
+
+- **Node.js process stays alive after finishing**: If using OCR, the worker pool stays warm for 10s by default. Use `await terminateOcr()` at the end of your script for a snappy exit.
+- **"Worker not found" in Browser**: Ensure `pdfWorkerSrc` is correctly pointed to the `pdf.worker.min.mjs` file matching version `5.6.205`.
+- **OCR accuracy is low**: Verify your `ocrConfig.language` matches the document content. Note that OCR quality depends on image resolution.
+- **Out of memory on large files**: For massive spreadsheets, consider using `ast.toText()` early and allowing the full AST object to be garbage-collected.
+
+For a comprehensive guide, visit our [Debugging & Troubleshooting Documentation](https://harshankur.github.io/officeParser/#spec/debugging).
+
 
 ## Known Limitations
 1. **ODT/ODS Charts**: Extraction may occasionally show inaccurate data when referencing external cell ranges or complex layout-based data.
@@ -500,7 +584,7 @@ const ast2 = await officeParser.parseOffice(file, {
 
 ## 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/OfficeParser.d.ts

@@ -32,7 +32,7 @@
  *
  * @module OfficeParser
  */
-import { OfficeParserAST, OfficeParserConfig } from './types';
+import { OfficeParserAST, OfficeParserConfig } from './types.js';
 /**
  * Main parser class providing office document parsing functionality.
  *
@@ -86,4 +86,13 @@ export declare class OfficeParser {
      * ```
      */
     static parseOffice(file: string | Buffer | ArrayBuffer, configOrCallback?: OfficeParserConfig | ((ast: OfficeParserAST, err?: any) => void), config?: OfficeParserConfig): Promise<OfficeParserAST>;
+    /**
+     * Terminates all active OCR workers and cleans up resources.
+     *
+     * This should be called when the application is shutting down or when OCR
+     * is no longer needed to prevent memory leaks and orphaned worker processes.
+     *
+     * @returns A promise that resolves when all workers have been terminated
+     */
+    static terminateOcr(): Promise<void>;
 }

package/dist/OfficeParser.js

@@ -33,50 +33,18 @@
  *
  * @module OfficeParser
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfficeParser = void 0;
-const fs = __importStar(require("fs"));
-const ExcelParser_1 = require("./parsers/ExcelParser");
-const OpenOfficeParser_1 = require("./parsers/OpenOfficeParser");
-const PdfParser_1 = require("./parsers/PdfParser");
-const PowerPointParser_1 = require("./parsers/PowerPointParser");
-const RtfParser_1 = require("./parsers/RtfParser");
-const WordParser_1 = require("./parsers/WordParser");
-const errorUtils_1 = require("./utils/errorUtils");
-const moduleLoader_1 = require("./utils/moduleLoader");
+const envUtils_js_1 = require("./utils/envUtils.js");
+const ExcelParser_js_1 = require("./parsers/ExcelParser.js");
+const OpenOfficeParser_js_1 = require("./parsers/OpenOfficeParser.js");
+const PdfParser_js_1 = require("./parsers/PdfParser.js");
+const PowerPointParser_js_1 = require("./parsers/PowerPointParser.js");
+const RtfParser_js_1 = require("./parsers/RtfParser.js");
+const WordParser_js_1 = require("./parsers/WordParser.js");
+const errorUtils_js_1 = require("./utils/errorUtils.js");
+const moduleLoader_js_1 = require("./utils/moduleLoader.js");
+const ocrUtils_js_1 = require("./utils/ocrUtils.js");
 /**
  * Main parser class providing office document parsing functionality.
  *
@@ -148,7 +116,11 @@ class OfficeParser {
             ocr: false,
             ocrLanguage: 'eng',
             includeRawContent: false,
+            serializeRawContent: true,
+            preserveXmlWhitespace: false,
             pdfWorkerSrc: '',
+            ocrConfig: {},
+            includeBreakNodes: false,
             ...actualConfig
         };
         let buffer = Buffer.alloc(0);
@@ -156,7 +128,7 @@ class OfficeParser {
         let filePath;
         try {
             if (!file) {
-                throw (0, errorUtils_1.getOfficeError)(errorUtils_1.OfficeErrorType.IMPROPER_ARGUMENTS, internalConfig);
+                throw (0, errorUtils_js_1.getOfficeError)(errorUtils_js_1.OfficeErrorType.IMPROPER_ARGUMENTS, internalConfig);
             }
             if (file instanceof ArrayBuffer) {
                 buffer = Buffer.from(file);
@@ -166,63 +138,79 @@ class OfficeParser {
             }
             else if (typeof file === 'string') {
                 filePath = file;
+                (0, envUtils_js_1.assertNode)('path-parsing');
+                // Safe to use dynamic import here as we've asserted we are in Node.
+                // Modern bundlers will still see this, but our browser builds 
+                // shim 'fs' so it won't crash at build time.
+                const fs = await import('fs');
                 if (!fs.existsSync(file)) {
-                    throw (0, errorUtils_1.getOfficeError)(errorUtils_1.OfficeErrorType.FILE_DOES_NOT_EXIST, internalConfig, file);
+                    throw (0, errorUtils_js_1.getOfficeError)(errorUtils_js_1.OfficeErrorType.FILE_DOES_NOT_EXIST, internalConfig, file);
                 }
                 if (fs.lstatSync(file).isDirectory()) {
-                    throw (0, errorUtils_1.getOfficeError)(errorUtils_1.OfficeErrorType.LOCATION_NOT_FOUND, internalConfig, file);
+                    throw (0, errorUtils_js_1.getOfficeError)(errorUtils_js_1.OfficeErrorType.LOCATION_NOT_FOUND, internalConfig, file);
                 }
                 buffer = fs.readFileSync(file);
                 ext = file.split('.').pop()?.toLowerCase() || '';
             }
             else {
-                throw (0, errorUtils_1.getOfficeError)(errorUtils_1.OfficeErrorType.INVALID_INPUT, internalConfig);
+                throw (0, errorUtils_js_1.getOfficeError)(errorUtils_js_1.OfficeErrorType.INVALID_INPUT, internalConfig);
             }
             if (!ext) {
-                const { fileTypeFromBuffer } = await (0, moduleLoader_1.loadFileType)();
+                const { fileTypeFromBuffer } = await (0, moduleLoader_js_1.loadFileType)();
                 const type = await fileTypeFromBuffer(buffer);
                 if (type) {
                     ext = type.ext.toLowerCase();
                 }
                 else {
-                    throw (0, errorUtils_1.getOfficeError)(errorUtils_1.OfficeErrorType.IMPROPER_BUFFERS, internalConfig);
+                    throw (0, errorUtils_js_1.getOfficeError)(errorUtils_js_1.OfficeErrorType.IMPROPER_BUFFERS, internalConfig);
                 }
             }
             let result;
             switch (ext) {
                 case 'docx':
-                    result = await (0, WordParser_1.parseWord)(buffer, internalConfig);
+                    result = await (0, WordParser_js_1.parseWord)(buffer, internalConfig);
                     break;
                 case 'pptx':
-                    result = await (0, PowerPointParser_1.parsePowerPoint)(buffer, internalConfig);
+                    result = await (0, PowerPointParser_js_1.parsePowerPoint)(buffer, internalConfig);
                     break;
                 case 'xlsx':
-                    result = await (0, ExcelParser_1.parseExcel)(buffer, internalConfig);
+                    result = await (0, ExcelParser_js_1.parseExcel)(buffer, internalConfig);
                     break;
                 case 'odt':
                 case 'odp':
                 case 'ods':
-                    result = await (0, OpenOfficeParser_1.parseOpenOffice)(buffer, internalConfig);
+                    result = await (0, OpenOfficeParser_js_1.parseOpenOffice)(buffer, internalConfig);
                     break;
                 case 'pdf':
-                    result = await (0, PdfParser_1.parsePdf)(buffer, internalConfig);
+                    result = await (0, PdfParser_js_1.parsePdf)(buffer, internalConfig);
                     break;
                 case 'rtf':
-                    result = await (0, RtfParser_1.parseRtf)(buffer, internalConfig);
+                    result = await (0, RtfParser_js_1.parseRtf)(buffer, internalConfig);
                     break;
                 default:
-                    throw (0, errorUtils_1.getOfficeError)(errorUtils_1.OfficeErrorType.EXTENSION_UNSUPPORTED, internalConfig, ext);
+                    throw (0, errorUtils_js_1.getOfficeError)(errorUtils_js_1.OfficeErrorType.EXTENSION_UNSUPPORTED, internalConfig, ext);
             }
             if (callback)
                 callback(result);
             return result;
         }
         catch (error) {
-            const wrappedError = (0, errorUtils_1.getWrappedError)(error, internalConfig, filePath);
+            const wrappedError = (0, errorUtils_js_1.getWrappedError)(error, internalConfig, filePath);
             if (callback)
                 callback(undefined, wrappedError);
             throw wrappedError;
         }
     }
+    /**
+     * Terminates all active OCR workers and cleans up resources.
+     *
+     * This should be called when the application is shutting down or when OCR
+     * is no longer needed to prevent memory leaks and orphaned worker processes.
+     *
+     * @returns A promise that resolves when all workers have been terminated
+     */
+    static async terminateOcr() {
+        await (0, ocrUtils_js_1.terminateOcr)();
+    }
 }
 exports.OfficeParser = OfficeParser;

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * officeparser CLI
+ *
+ * Allows running officeparser from the command line:
+ *   npx officeparser file.docx
+ *   officeparser file.docx --toText=true
+ *   officeparser file.docx --ocr=true --extractAttachments=true
+ *
+ * Options (--key=value):
+ *   --toText=true             Output plain text instead of JSON AST
+ *   --ocr=true                Enable OCR for images
+ *   --ocrLanguage=eng         OCR language (default: eng)
+ *   --extractAttachments=true Extract embedded attachments
+ *   --ignoreNotes=true        Ignore footnotes/endnotes
+ *   --putNotesAtLast=true     Move notes to end of document
+ *   --includeRawContent=true  Include raw content in AST
+ *   --outputErrorToConsole=true  Log errors to console
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * officeparser CLI
+ *
+ * Allows running officeparser from the command line:
+ *   npx officeparser file.docx
+ *   officeparser file.docx --toText=true
+ *   officeparser file.docx --ocr=true --extractAttachments=true
+ *
+ * Options (--key=value):
+ *   --toText=true             Output plain text instead of JSON AST
+ *   --ocr=true                Enable OCR for images
+ *   --ocrLanguage=eng         OCR language (default: eng)
+ *   --extractAttachments=true Extract embedded attachments
+ *   --ignoreNotes=true        Ignore footnotes/endnotes
+ *   --putNotesAtLast=true     Move notes to end of document
+ *   --includeRawContent=true  Include raw content in AST
+ *   --outputErrorToConsole=true  Log errors to console
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const OfficeParser_js_1 = require("./OfficeParser.js");
+const args = process.argv.slice(2);
+let fileArg;
+let toText = false;
+let verbose = false;
+const configArgs = [];
+function isConfigOption(arg) {
+    return arg.startsWith('--') && arg.includes('=');
+}
+args.forEach(arg => {
+    if (isConfigOption(arg)) {
+        configArgs.push(arg);
+    }
+    else if (!fileArg) {
+        fileArg = arg;
+    }
+});
+if (fileArg) {
+    const config = {};
+    configArgs.forEach(arg => {
+        const [key, value] = arg.split('=');
+        const cleanKey = key.replace('--', '');
+        const lowerValue = value.toLowerCase();
+        const boolValue = lowerValue === 'true' ? true : (lowerValue === 'false' ? false : undefined);
+        if (cleanKey === 'toText') {
+            if (boolValue !== undefined)
+                toText = boolValue;
+            else
+                console.warn(`Invalid value for toText: ${value}`);
+        }
+        else if (cleanKey === 'verbose') {
+            if (boolValue !== undefined)
+                verbose = boolValue;
+            else
+                console.warn(`Invalid value for verbose: ${value}`);
+        }
+        else {
+            // @ts-ignore
+            if (boolValue !== undefined)
+                config[cleanKey] = boolValue;
+            // @ts-ignore
+            else
+                config[cleanKey] = value;
+        }
+    });
+    OfficeParser_js_1.OfficeParser.parseOffice(fileArg, config)
+        .then(async (ast) => {
+        if (toText) {
+            process.stdout.write(ast.toText() + '\n');
+        }
+        else {
+            process.stdout.write(JSON.stringify(ast, null, 2) + '\n');
+        }
+        // Ensure OCR workers are terminated for clean CLI exit
+        if (config.ocr) {
+            await OfficeParser_js_1.OfficeParser.terminateOcr();
+        }
+    })
+        .catch(async (err) => {
+        console.error(`Error parsing file "${fileArg}":`);
+        if (verbose) {
+            console.error(err);
+        }
+        else {
+            console.error(err.message || err);
+            console.error('Use --verbose=true for full stack trace.');
+        }
+        // Ensure OCR workers are terminated even on error
+        if (config.ocr) {
+            await OfficeParser_js_1.OfficeParser.terminateOcr();
+        }
+        process.exit(1);
+    });
+}
+else {
+    console.log('Usage: officeparser <file> [--option=value]');
+    console.log('');
+    console.log('Options:');
+    console.log('  --toText=true                Output plain text instead of JSON AST');
+    console.log('  --ocr=true                   Enable OCR for images');
+    console.log('  --ocrLanguage=eng            OCR language (default: eng)');
+    console.log('  --extractAttachments=true    Extract embedded attachments');
+    console.log('  --ignoreNotes=true           Ignore footnotes/endnotes');
+    console.log('  --putNotesAtLast=true        Move notes to end of document');
+    console.log('  --includeRawContent=true     Include raw content in AST');
+    console.log('  --serializeRawContent=true   Serialize raw XML content (default: true)');
+    console.log('  --preserveXmlWhitespace=true Preserve whitespace in serialized XML (default: false)');
+    console.log('  --includeBreakNodes=false    Include break nodes (DOCX only, default: false)');
+    console.log('  --verbose=true               Show full error stack traces');
+    console.log('');
+    console.log('Examples:');
+    console.log('  officeparser document.docx');
+    console.log('  officeparser document.docx --toText=true');
+    console.log('  officeparser report.pdf --ocr=true --extractAttachments=true');
+    console.log('  officeparser complex.docx --serializeRawContent=false --includeRawContent=true');
+}