officeparser 7.0.3 → 7.1.0

package/README.md

@@ -178,6 +178,60 @@ const ast = await officeParser.parseOffice(buffer);
 > const ast = await officeParser.parseOffice(markdownBuffer, { fileType: 'md' });
 > ```
 
+### Cancellation with AbortSignal
+
+You can pass a standard `AbortSignal` (e.g. from an `AbortController`) to cancel an active parse operation. This is especially useful for setting request-level timeouts or canceling long-running parses (like large PDFs with OCR).
+
+```js
+const controller = new AbortController();
+
+// Cancel parsing if it takes longer than 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+try {
+    const ast = await officeParser.parseOffice('large_scanned_file.pdf', {
+        abortSignal: controller.signal,
+        ocr: true
+    });
+} catch (err) {
+    if (err.name === 'AbortError') {
+        console.log('Parsing was cancelled.');
+    } else {
+        console.error('Parsing failed:', err);
+    }
+}
+```
+
+> [!IMPORTANT]
+> **AbortError Propagation**
+> When parsing is cancelled via `AbortSignal`, the parser rejects with a standard `AbortError` (a `DOMException` or an Error with `name: 'AbortError'`).
+> This error is *not* wrapped in standard OfficeParser error types so that you can reliably detect cancellation using `error.name === 'AbortError'`.
+
+> [!NOTE]
+> **Worker Cleanup on Abort**
+> If an OCR job is actively running in the background when the signal is aborted, `officeParser` automatically terminates the Tesseract worker process immediately and removes it from the pool to prevent thread/memory leaks.
+
+### Custom OCR Timeouts
+
+To prevent the parser from hanging indefinitely due to slow network connections (when downloading Tesseract language datasets) or complex image processing, you can configure granular timeouts under `ocrConfig.timeout`.
+
+```js
+const ast = await officeParser.parseOffice('scanned_document.pdf', {
+    ocr: true,
+    ocrConfig: {
+        timeout: {
+            workerLoad: 30000,    // 30s max to load worker & download language training files
+            recognition: 15000,   // 15s max per image text recognition
+            autoTerminate: 10000  // 10s of inactivity before terminating idle workers
+        }
+    }
+});
+```
+
+> [!TIP]
+> **Non-Fatal Timeout Recovery**
+> If `workerLoad` or `recognition` timeouts are exceeded, the parser will log a warning in `ast.warnings` and **continue parsing the rest of the document**. The overall promise resolves successfully with the text extracted from the document layers (rather than failing the entire parse).
+
 ### `ast.to()` — Generate from AST
 
 The preferred way to convert a parsed AST to another format. Returns a `ConversionResult`.
@@ -610,6 +664,7 @@ Pass as the second argument to `parseOffice(file, config)`.
 | `csvDelimiter` | `string` | `','` | Input delimiter when parsing CSV files |
 | `pdfWorkerSrc` | `string` | CDN (jsDelivr) | Path/URL to `pdf.worker.min.mjs` (required in browser) |
 | `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal parsing issues |
+| `abortSignal` | `AbortSignal \| null` | `null` | Optional signal to cancel parsing (rejects with AbortError) |
 | `outputErrorToConsole` | `boolean` | `false` | **Deprecated.** Use `onWarning` instead |
 
 ---
@@ -630,6 +685,7 @@ Options shared by all generator formats. Pass to `OfficeGenerator.generate(ast,
 | `styleMap` | `string[] \| StructuredStyleMapping[]` | `[]` | Custom semantic style mappings |
 | `onNode` | `(node) => string \| false \| void` | — | Per-node callback for filtering, overriding, or mutating |
 | `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal generation issues |
+| `abortSignal` | `AbortSignal \| null` | `null` | Optional signal to cancel the generation operation (rejects with AbortError) |
 
 ---
 
@@ -732,6 +788,7 @@ Pass as `pdfConfig` inside `GeneratorConfig`. Requires the optional `puppeteer`
 | `footerTemplate` | `string` | `''` | HTML template for the print footer |
 | `scale` | `number` | `1` | Rendering scale factor |
 | `launchOptions` | `object` | headless defaults | Puppeteer launch options (e.g., `executablePath`) |
+| `timeout` | `number` | `30000` | PDF rendering timeout in milliseconds. Set to `0` to disable. |
 
 ### CsvGeneratorConfig
 
@@ -807,6 +864,7 @@ Configuration for `OfficeConverter.convert(file, format, config)`.
 | `maxChunkSize` | `number` | `2000` | Max characters even if similarity stays high |
 | `bufferSize` | `number` | `1` | Surrounding sentences used when computing similarity |
 | `embeddingBatchSize` | `number` | `50` | Sentences per embedding API batch |
+| `timeout` | `number` | `10000` | Timeout in milliseconds for individual embedding API calls. Set to `0` to disable. |
 
 ---
 
@@ -826,7 +884,8 @@ When `ocr: true` is set, `officeParser` maintains an intelligent **Smart Worker
 | `workerPath` | `string` | `''` | Custom path to Tesseract worker script |
 | `corePath` | `string` | `''` | Custom path to Tesseract core script |
 | `langPath` | `string` | `''` | Custom path for language data files |
-| `autoTerminateTimeout` | `number` | `10000` | Inactivity timeout in ms before auto-teardown (0 = disabled) |
+| `timeout` | `OcrTimeoutConfig` | `{}` | Consolidated timeouts: `autoTerminate`, `workerLoad`, `recognition` |
+| `autoTerminateTimeout` | `number` | `10000` | **Deprecated.** Use `timeout.autoTerminate` instead |
 
 See all language codes at [tesseract-ocr.github.io](https://tesseract-ocr.github.io/tessdoc/Data-Files).
 

package/dist/OfficeParser.js

@@ -241,6 +241,12 @@ class OfficeParser {
             return result;
         }
         catch (error) {
+            // AbortError must pass through untouched so callers can distinguish a
+            // deliberate cancellation (err.name === 'AbortError') from a real parse failure.
+            // getWrappedError always creates a plain new Error(), which would strip the
+            // AbortError identity and break any instanceof / name checks on the caller side.
+            if (error?.name === 'AbortError')
+                throw error;
             const wrappedError = (0, errorUtils_js_1.getWrappedError)(error, internalConfig, filePath);
             if (callback)
                 callback(undefined, wrappedError);

package/dist/defaults.js

@@ -13,6 +13,12 @@ exports.DEFAULT_SENTENCE_BOUNDARY_REGEX = /[.!?。！？]/;
  * Common abbreviations that should not trigger a sentence split when followed by a period.
  */
 exports.DEFAULT_ABBREVIATIONS = ['Mr', 'Dr', 'Ms', 'Inc', 'Ltd', 'Prof', 'Sr', 'Jr', 'vs', 'etc'];
+/** Default timeout values for OCR */
+const DEFAULT_OCR_TIMEOUT = {
+    autoTerminate: 10000,
+    workerLoad: 60000,
+    recognition: 30000,
+};
 /**
  * Default configuration for OCR.
  */
@@ -21,7 +27,12 @@ const DEFAULT_OCR_CONFIG = {
     workerPath: '',
     corePath: '',
     langPath: '',
-    autoTerminateTimeout: 10000,
+    // Preferred: consolidated timeout object.  New code should always read from here.
+    timeout: DEFAULT_OCR_TIMEOUT,
+    // Kept for backward compatibility.  When timeout.autoTerminate is set (as above),
+    // the ocrUtils resolution logic will prefer timeout.autoTerminate over this flat field.
+    autoTerminateTimeout: DEFAULT_OCR_TIMEOUT.autoTerminate,
+    abortSignal: null,
 };
 /**
  * Default configuration for the OfficeParser.
@@ -37,6 +48,7 @@ exports.DEFAULT_OFFICE_PARSER_CONFIG = {
     ocr: false,
     ocrLanguage: 'eng',
     ocrConfig: DEFAULT_OCR_CONFIG,
+    abortSignal: null,
     serializeRawContent: true,
     preserveXmlWhitespace: false,
     pdfWorkerSrc: DEFAULT_PDF_WORKER_SRC,
@@ -75,6 +87,7 @@ const DEFAULT_PDF_GENERATOR_CONFIG = {
         headless: true,
         args: ['--no-sandbox', '--disable-setuid-sandbox']
     },
+    timeout: 30000,
 };
 /**
  * Default configuration for CSV generation.
@@ -143,6 +156,7 @@ exports.DEFAULT_SEMANTIC_CHUNKING_CONFIG = {
     lengthFunction: (text) => text.length,
     sentenceBoundaryRegex: exports.DEFAULT_SENTENCE_BOUNDARY_REGEX,
     abbreviations: exports.DEFAULT_ABBREVIATIONS,
+    timeout: 10000,
 };
 /**
  * The resolved default chunking config (uses document-structure as default strategy).
@@ -162,6 +176,7 @@ exports.DEFAULT_GENERATOR_CONFIG = {
     includeImages: true,
     includeCharts: true,
     ignoreInternalLinks: false,
+    abortSignal: null,
     htmlConfig: DEFAULT_HTML_GENERATOR_CONFIG,
     mdConfig: DEFAULT_MD_GENERATOR_CONFIG,
     pdfConfig: DEFAULT_PDF_GENERATOR_CONFIG,

package/dist/generators/ChunkingGenerator.js

@@ -39,6 +39,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
      * Note: ConversionResult.value is a JSON string of OfficeChunk[] for the 'chunks' destination.
      */
     async generate() {
+        (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
         let chunks;
         switch (this.chunkConfig.strategy) {
             case 'fixed-size':
@@ -186,6 +187,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
         return this.finalizeChunks(chunks, config);
     }
     async processNodeForStructure(node, config, splitBy, maxChunkSize, measure, chunks, contextStack) {
+        (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
         // Check for node override or skip
         const override = await this.handleOnNode(node);
         if (override === false)
@@ -412,7 +414,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
         if (sentences.length === 0)
             return [];
         // Embed all sentences in batches to avoid rate limiting
-        const embeddings = await this.batchEmbeddings(sentences, config.embeddingFunction, batchSize);
+        const embeddings = await this.batchEmbeddings(sentences, config.embeddingFunction, batchSize, config.timeout);
         // Calculate cosine similarity between adjacent sentence windows
         const chunks = [];
         let currentSentences = [];
@@ -479,6 +481,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
         let currentPage;
         let currentSheet;
         const walk = async (node) => {
+            (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
             const override = await this.handleOnNode(node);
             if (override === false)
                 return;
@@ -533,6 +536,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
         let currentPage;
         let currentSheet;
         const walk = async (node) => {
+            (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
             const override = await this.handleOnNode(node);
             if (override === false)
                 return;
@@ -602,11 +606,27 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
     /**
      * Helper to process embeddings in sequential batches to avoid API rate limits and memory issues.
      */
-    async batchEmbeddings(sentences, embedFn, batchSize = 50) {
+    async batchEmbeddings(sentences, embedFn, batchSize = 50, timeoutMs) {
         const results = [];
         for (let i = 0; i < sentences.length; i += batchSize) {
+            (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
             const batch = sentences.slice(i, i + batchSize);
-            const batchResults = await Promise.all(batch.map(s => embedFn(s.text)));
+            const batchPromises = batch.map(s => {
+                const call = embedFn(s.text);
+                if (timeoutMs !== undefined && timeoutMs > 0) {
+                    let timerId;
+                    const timeoutPromise = new Promise((_, reject) => {
+                        timerId = setTimeout(() => {
+                            reject(new Error(`Embedding call timed out after ${timeoutMs}ms`));
+                        }, timeoutMs);
+                    });
+                    return Promise.race([call, timeoutPromise]).finally(() => {
+                        clearTimeout(timerId);
+                    });
+                }
+                return call;
+            });
+            const batchResults = await Promise.all(batchPromises);
             results.push(...batchResults);
         }
         return results;

package/dist/generators/PdfGenerator.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PdfGenerator = void 0;
 const types_js_1 = require("../types.js");
 const envUtils_js_1 = require("../utils/envUtils.js");
+const errorUtils_js_1 = require("../utils/errorUtils.js");
 const BaseGenerator_js_1 = require("./BaseGenerator.js");
 const HtmlGenerator_js_1 = require("./HtmlGenerator.js");
 /**
@@ -44,6 +45,24 @@ class PdfGenerator extends BaseGenerator_js_1.BaseGenerator {
      * Uses dynamic import to avoid bundling puppeteer into the library core.
      */
     async generateInNode(html) {
+        const signal = this.config.abortSignal;
+        if (signal?.aborted) {
+            throw (0, errorUtils_js_1.getAbortError)();
+        }
+        let browser;
+        const onAbort = async () => {
+            if (browser) {
+                try {
+                    await browser.close();
+                }
+                catch (e) {
+                    // ignore
+                }
+            }
+        };
+        if (signal) {
+            signal.addEventListener('abort', onAbort);
+        }
         try {
             // Dynamic import for peer dependency
             // @ts-ignore
@@ -70,11 +89,16 @@ class PdfGenerator extends BaseGenerator_js_1.BaseGenerator {
             // to ensure transparency about the environment state. Programmatically fixing this
             // would require force-downloading a ~300MB arm64 browser binary or switching to 
             // a system-installed Chrome, both of which are too intrusive for a library.
-            const browser = await puppeteer.launch(launchOptions);
+            browser = await puppeteer.launch(launchOptions);
             const page = await browser.newPage();
+            const pdfConfig = this.config.pdfConfig;
+            const timeout = pdfConfig.timeout;
+            if (timeout !== undefined && timeout > 0) {
+                page.setDefaultTimeout(timeout);
+                page.setDefaultNavigationTimeout(timeout);
+            }
             // Set content and wait for network/assets to load
             await page.setContent(html, { waitUntil: 'networkidle0' });
-            const pdfConfig = this.config.pdfConfig;
             const pdfBuffer = await page.pdf({
                 format: pdfConfig.format,
                 width: pdfConfig.width,
@@ -88,18 +112,41 @@ class PdfGenerator extends BaseGenerator_js_1.BaseGenerator {
                 footerTemplate: pdfConfig.footerTemplate,
             });
             await browser.close();
+            browser = null;
             return {
                 value: new Uint8Array(pdfBuffer),
                 messages: this.messages
             };
         }
         catch (err) {
-            this.warn(types_js_1.OfficeWarningType.DEPENDENCY_LOAD_FAILED, `puppeteer. Please install it with 'npm install puppeteer'. Error: ${err.message}`);
+            if (browser) {
+                try {
+                    await browser.close();
+                }
+                catch (e) {
+                    // ignore
+                }
+                browser = null;
+            }
+            if (signal?.aborted) {
+                throw (0, errorUtils_js_1.getAbortError)();
+            }
+            if (err.message && (err.message.includes('timeout') || err.message.includes('Timeout'))) {
+                this.warn(types_js_1.OfficeWarningType.PAGE_LOAD_FAILED, `PDF generation timed out: ${err.message}`);
+            }
+            else {
+                this.warn(types_js_1.OfficeWarningType.DEPENDENCY_LOAD_FAILED, `puppeteer. Please install it with 'npm install puppeteer'. Error: ${err.message}`);
+            }
             return {
-                value: '',
+                value: new Uint8Array(),
                 messages: this.messages
             };
         }
+        finally {
+            if (signal) {
+                signal.removeEventListener('abort', onAbort);
+            }
+        }
     }
     /**
      * Browser implementation using hidden iframe and native print.

package/dist/officeparser.browser.d.ts

@@ -30,7 +30,9 @@ export declare enum OfficeErrorType {
 	/** Output mapping in style mapping is invalid */
 	INVALID_OUTPUT_MAPPING = "INVALID_OUTPUT_MAPPING",
 	/** Semantic chunking strategy is selected but no embedding function is provided */
-	MISSING_EMBEDDING_FUNCTION = "MISSING_EMBEDDING_FUNCTION"
+	MISSING_EMBEDDING_FUNCTION = "MISSING_EMBEDDING_FUNCTION",
+	/** The operation was aborted */
+	OPERATION_ABORTED = "OPERATION_ABORTED"
 }
 /**
  * Standard warning types for OfficeParser.
@@ -70,6 +72,68 @@ export declare enum OfficeWarningType {
 	/** A node was skipped because it only contained whitespace */
 	WHITESPACE_NODE_SKIPPED = "WHITESPACE_NODE_SKIPPED"
 }
+/**
+ * Consolidated timeout settings for OCR operations.
+ * Preferred over the individual flat timeout properties on {@link OcrConfig},
+ * which are now deprecated.
+ *
+ * If a key is present here, it takes priority over the corresponding deprecated
+ * flat property (e.g. `timeout.autoTerminate` wins over `autoTerminateTimeout`).
+ * Set any value to `0` to disable that specific timeout.
+ */
+export interface OcrTimeoutConfig {
+	/**
+	 * Timeout in milliseconds of inactivity before the OCR worker pool is
+	 * automatically terminated and freed.
+	 *
+	 * The timer resets every time a new OCR job is enqueued.  When the last
+	 * job completes and this duration passes without a new one, the entire
+	 * worker pool is torn down so that no background threads keep the Node.js
+	 * process alive unnecessarily.
+	 *
+	 * Set to `0` to keep workers alive indefinitely (useful when you want to
+	 * call {@link terminateOcr} manually at shutdown time).
+	 * Default is 10,000 ms (10 seconds).
+	 */
+	autoTerminate?: number;
+	/**
+	 * Timeout in milliseconds for initializing a Tesseract worker
+	 * (loading the JS runtime, downloading or loading the `.traineddata`
+	 * language file) or for re-initializing an existing worker with a
+	 * different language.
+	 *
+	 * Multi-language combinations (e.g. `'por+eng+spa'`) must download a
+	 * separate `.traineddata` file for each language and are therefore
+	 * particularly susceptible to slow networks.  Tune this value upward if
+	 * your OCR environment has high network latency or if you are loading
+	 * languages from disk in a large container image.
+	 *
+	 * When the timeout fires, the failed job is rejected with a non-fatal
+	 * {@link OfficeWarningType.OCR_FAILED} warning and parsing continues
+	 * without OCR output for that image.  The stalled worker is terminated
+	 * and removed from the pool to prevent thread leaks.
+	 *
+	 * Set to `0` to wait indefinitely (not recommended for production; a hung
+	 * network request will block the entire OCR queue for that language).
+	 * Default is 60,000 ms (60 seconds).
+	 */
+	workerLoad?: number;
+	/**
+	 * Timeout in milliseconds for the actual OCR text-recognition call
+	 * (`worker.recognize(image)`) on an already-initialized Tesseract worker.
+	 *
+	 * Recognition time scales with image resolution and the number of active
+	 * languages.  Very high-resolution scans or unusual character sets can
+	 * exceed the default.  If this timeout fires, the job is rejected with a
+	 * non-fatal {@link OfficeWarningType.OCR_FAILED} warning; the worker is
+	 * terminated and evicted from the pool because its internal state after a
+	 * mid-recognition timeout is undefined.
+	 *
+	 * Set to `0` to wait indefinitely.
+	 * Default is 30,000 ms (30 seconds).
+	 */
+	recognition?: number;
+}
 /**
  * Configuration options for OCR.
  */
@@ -104,11 +168,33 @@ export interface OcrConfig {
 	 */
 	langPath?: string;
 	/**
+	 * Consolidated timeout settings for all OCR operations.
+	 *
+	 * Prefer this over the deprecated flat timeout properties.
+	 * If `timeout.autoTerminate` is set, it takes priority over the deprecated `autoTerminateTimeout`.
+	 */
+	timeout?: OcrTimeoutConfig;
+	/**
+	 * @deprecated Use `timeout.autoTerminate` instead.
+	 *
 	 * Timeout in milliseconds of inactivity before the OCR worker pool is automatically terminated.
 	 * Set to 0 to disable auto-termination.
 	 * Default is 10,000 (10 seconds).
+	 *
+	 * If `timeout.autoTerminate` is also set, that value takes priority over this one.
 	 */
 	autoTerminateTimeout?: number;
+	/**
+	 * An optional AbortSignal propagated from the main parser configuration to abort active OCR jobs.
+	 * If the signal is aborted:
+	 * 1. Any pending OCR jobs in the scheduler queue are rejected immediately.
+	 * 2. Any active OCR job running on a Tesseract worker will reject, the worker will be
+	 *    terminated, and it will be removed from the pool to avoid hanging worker threads.
+	 *
+	 * Developers should prefer passing this at the top level of `parseOffice` (as `config.abortSignal`),
+	 * which automatically propagates here.
+	 */
+	abortSignal?: AbortSignal | null;
 }
 /**
  * Configuration options for the OfficeParser.
@@ -175,6 +261,20 @@ export interface OfficeParserConfig {
 	 * If provided, `ocrLanguage` will be ignored in favor of `ocrConfig.language`.
 	 */
 	ocrConfig?: OcrConfig;
+	/**
+	 * An optional AbortSignal to cancel the parsing operation.
+	 * When aborted, the parser immediately rejects with a standard AbortError (DOMException).
+	 *
+	 * ### Format-Specific Abort Behavior:
+	 * - **PDF**: Checked between page loads and before individual image OCR operations.
+	 * - **RTF**: Checked before parsing/traversal and before running OCR on image attachments.
+	 * - **DOCX/XLSX/PPTX/ODF**: Checked during zip decompression before loading and parsing XML files.
+	 * - **CSV/MD/HTML**: Checked at the start of the parsing phase.
+	 *
+	 * Note: If an OCR operation is currently running on a Tesseract worker when aborted,
+	 * the worker will be terminated and removed from the worker pool automatically to prevent leaks.
+	 */
+	abortSignal?: AbortSignal | null;
 	/**
 	 * Flag to serialize raw content (XML) as clean, formatted strings.
 	 * Only relevant when `includeRawContent` is true.
@@ -363,6 +463,12 @@ export interface CommonGeneratorConfig {
 	 * Defaults to false.
 	 */
 	ignoreInternalLinks?: boolean;
+	/**
+	 * An optional AbortSignal to cancel the generation operation.
+	 * When aborted, the generator immediately rejects with a standard AbortError.
+	 * Currently supported by PdfGenerator and ChunkingGenerator.
+	 */
+	abortSignal?: AbortSignal | null;
 }
 /**
  * Destination-aware generator configuration.
@@ -474,6 +580,12 @@ export interface PdfGeneratorConfig {
 	 * Useful for setting custom executable paths or args in CI/CD.
 	 */
 	launchOptions?: any;
+	/**
+	 * Timeout in milliseconds for PDF generation.
+	 * Limits the time spent waiting for Puppeteer to launch, load content, and render PDF.
+	 * Defaults to 30000 ms (30 seconds). Set to 0 to disable.
+	 */
+	timeout?: number;
 }
 /**
  * Structured style mapping definition for the StyleMapper.
@@ -779,6 +891,11 @@ export interface SemanticChunkingConfig extends BaseChunkingConfig {
 	 * Default is 50.
 	 */
 	embeddingBatchSize?: number;
+	/**
+	 * Timeout in milliseconds for individual embedding API calls.
+	 * Defaults to 10000 ms (10 seconds). Set to 0 to disable.
+	 */
+	timeout?: number;
 }
 /**
  * Discriminated union of all chunking strategy configurations.