officeparser 7.0.3 → 7.1.0

package/dist/types.d.ts

@@ -28,7 +28,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.
@@ -68,6 +70,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.
  */
@@ -102,11 +166,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.
@@ -173,6 +259,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.
@@ -366,6 +466,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.
@@ -494,6 +600,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.
@@ -799,6 +911,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.

package/dist/types.js

@@ -33,6 +33,8 @@ var OfficeErrorType;
     OfficeErrorType["INVALID_OUTPUT_MAPPING"] = "INVALID_OUTPUT_MAPPING";
     /** Semantic chunking strategy is selected but no embedding function is provided */
     OfficeErrorType["MISSING_EMBEDDING_FUNCTION"] = "MISSING_EMBEDDING_FUNCTION";
+    /** The operation was aborted */
+    OfficeErrorType["OPERATION_ABORTED"] = "OPERATION_ABORTED";
 })(OfficeErrorType || (exports.OfficeErrorType = OfficeErrorType = {}));
 /**
  * Standard warning types for OfficeParser.

package/dist/utils/configUtils.js

@@ -66,12 +66,25 @@ function resolveParserConfig(userConfig) {
     const { ocrConfig, ...rest } = userConfig;
     Object.assign(config, rest);
     if (ocrConfig) {
-        config.ocrConfig = { ...config.ocrConfig, ...ocrConfig };
+        const { timeout, ...ocrRest } = ocrConfig;
+        config.ocrConfig = {
+            ...config.ocrConfig,
+            ...ocrRest,
+            timeout: {
+                autoTerminate: timeout?.autoTerminate !== undefined ? timeout.autoTerminate : config.ocrConfig.timeout.autoTerminate,
+                workerLoad: timeout?.workerLoad !== undefined ? timeout.workerLoad : config.ocrConfig.timeout.workerLoad,
+                recognition: timeout?.recognition !== undefined ? timeout.recognition : config.ocrConfig.timeout.recognition,
+            }
+        };
     }
     // 3. Handle legacy ocrLanguage mapping if not explicitly set in ocrConfig
     if (userConfig.ocrLanguage && !userConfig.ocrConfig?.language) {
         config.ocrConfig.language = userConfig.ocrLanguage;
     }
+    // 4. Propagate the top-level abortSignal to ocrConfig so the OCR subsystem is aware of it
+    if (config.abortSignal) {
+        config.ocrConfig.abortSignal = config.abortSignal;
+    }
     return config;
 }
 /**

package/dist/utils/errorUtils.d.ts

@@ -27,6 +27,11 @@ export declare const getOfficeError: (type: OfficeErrorType, config?: OfficePars
  * Wraps an existing error with OfficeParser context and performs corruption detection.
  * Optionally logs the error to console.
  *
+ * **Important**: Do NOT pass AbortErrors to this function. AbortErrors (err.name === 'AbortError')
+ * represent deliberate user cancellation and must be re-thrown as-is from the catch block so that
+ * callers can reliably detect them via `err.name === 'AbortError'` or `err instanceof DOMException`.
+ * This function always returns a plain `new Error(...)`, which would strip the AbortError identity.
+ *
  * @param error - The original error object
  * @param config - Parser configuration
  * @param filePath - Optional file path for context
@@ -44,3 +49,18 @@ export declare const getWrappedError: (error: any, config: OfficeParserConfig, f
  * @param error - Optional original error object
  */
 export declare const logWarning: (type: OfficeWarningType, config?: OfficeParserConfig, info?: any, error?: any) => void;
+/**
+ * Creates and returns a standard AbortError (DOMException if available).
+ * Used when the user signals cancellation of the parser operation.
+ *
+ * @returns Error object representing the abort action
+ */
+export declare const getAbortError: () => Error;
+/**
+ * Checks the provided AbortSignal and throws an AbortError if it was aborted.
+ * Helps cleanly interrupt loops and asynchronous phases of parsing.
+ *
+ * @param signal - Optional AbortSignal to inspect
+ * @throws {DOMException} If the signal has been aborted
+ */
+export declare const checkAbortSignal: (signal?: AbortSignal | null) => void;

package/dist/utils/errorUtils.js

@@ -7,7 +7,7 @@
  * consistent error reporting across all parsers and the main entry point.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logWarning = exports.getWrappedError = exports.getOfficeError = exports.getWarningMessage = void 0;
+exports.checkAbortSignal = exports.getAbortError = exports.logWarning = exports.getWrappedError = exports.getOfficeError = exports.getWarningMessage = void 0;
 const types_js_1 = require("../types.js");
 /** Error header prefix for all error messages */
 const ERRORHEADER = "[OfficeParser]: ";
@@ -28,7 +28,8 @@ const ERROR_MESSAGES = {
     [types_js_1.OfficeErrorType.INVALID_STYLE_MAPPING]: (mapping) => `Invalid style mapping string: ${mapping}`,
     [types_js_1.OfficeErrorType.INVALID_SELECTOR]: (selector) => `Invalid selector: ${selector}`,
     [types_js_1.OfficeErrorType.INVALID_OUTPUT_MAPPING]: (output) => `Invalid output mapping: ${output}`,
-    [types_js_1.OfficeErrorType.MISSING_EMBEDDING_FUNCTION]: `Semantic chunking requires an "embeddingFunction" to be provided in chunksConfig. This function must accept a string and return a Promise resolving to a number array (vector).`
+    [types_js_1.OfficeErrorType.MISSING_EMBEDDING_FUNCTION]: `Semantic chunking requires an "embeddingFunction" to be provided in chunksConfig. This function must accept a string and return a Promise resolving to a number array (vector).`,
+    [types_js_1.OfficeErrorType.OPERATION_ABORTED]: `The operation was aborted.`
 };
 /**
  * Lookup table for warning messages.
@@ -118,6 +119,11 @@ exports.getOfficeError = getOfficeError;
  * Wraps an existing error with OfficeParser context and performs corruption detection.
  * Optionally logs the error to console.
  *
+ * **Important**: Do NOT pass AbortErrors to this function. AbortErrors (err.name === 'AbortError')
+ * represent deliberate user cancellation and must be re-thrown as-is from the catch block so that
+ * callers can reliably detect them via `err.name === 'AbortError'` or `err instanceof DOMException`.
+ * This function always returns a plain `new Error(...)`, which would strip the AbortError identity.
+ *
  * @param error - The original error object
  * @param config - Parser configuration
  * @param filePath - Optional file path for context
@@ -176,3 +182,32 @@ const logWarning = (type, config, info, error) => {
     reportIssue(issue, config);
 };
 exports.logWarning = logWarning;
+/**
+ * Creates and returns a standard AbortError (DOMException if available).
+ * Used when the user signals cancellation of the parser operation.
+ *
+ * @returns Error object representing the abort action
+ */
+const getAbortError = () => {
+    const message = ERROR_MESSAGES[types_js_1.OfficeErrorType.OPERATION_ABORTED];
+    if (typeof DOMException !== 'undefined') {
+        return new DOMException(message, 'AbortError');
+    }
+    const err = new Error(message);
+    err.name = 'AbortError';
+    return err;
+};
+exports.getAbortError = getAbortError;
+/**
+ * Checks the provided AbortSignal and throws an AbortError if it was aborted.
+ * Helps cleanly interrupt loops and asynchronous phases of parsing.
+ *
+ * @param signal - Optional AbortSignal to inspect
+ * @throws {DOMException} If the signal has been aborted
+ */
+const checkAbortSignal = (signal) => {
+    if (signal?.aborted) {
+        throw (0, exports.getAbortError)();
+    }
+};
+exports.checkAbortSignal = checkAbortSignal;

package/dist/utils/moduleLoader.js

@@ -14,7 +14,7 @@ exports.loadPdfJs = loadPdfJs;
 const envUtils_js_1 = require("./envUtils.js");
 async function loadNodeEsmModule(specifier) {
     // In Node.js, we resolve the specifier to an absolute file URL.
-    // This ensures that the dynamic import() call (executed via new Function)
+    // This ensures that the dynamic import() call
     // always finds the correct module regardless of the caller's context.
     // This is especially important in Node 18 for sub-paths of packages.
     try {
@@ -22,11 +22,11 @@ async function loadNodeEsmModule(specifier) {
         // @ts-ignore - require.resolve is available in Node.js
         const absolutePath = require.resolve(specifier);
         const fileUrl = pathToFileURL(absolutePath).href;
-        return new Function('s', 'return import(s)')(fileUrl);
+        return import(fileUrl);
     }
     catch (e) {
         // Fallback for cases where require.resolve might fail (e.g. non-file specifiers)
-        return new Function('s', 'return import(s)')(specifier);
+        return import(specifier);
     }
 }
 /**