officeparser 7.0.2 → 7.1.0

package/dist/utils/ocrUtils.js

@@ -13,6 +13,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.terminateOcr = exports.performOcr = void 0;
 const envUtils_js_1 = require("./envUtils.js");
+const errorUtils_js_1 = require("./errorUtils.js");
+/**
+ * Wraps a promise in a timeout.
+ *
+ * @param promise - The promise to wrap
+ * @param ms - Timeout duration in milliseconds
+ * @param errMsg - Error message to throw if timeout occurs
+ * @returns The wrapped promise
+ */
+function withTimeout(promise, ms, errMsg) {
+    let id;
+    const timeout = new Promise((_, reject) => {
+        id = setTimeout(() => {
+            reject(new Error(errMsg));
+        }, ms);
+    });
+    return Promise.race([promise, timeout]).then((res) => { clearTimeout(id); return res; }, (err) => { clearTimeout(id); throw err; });
+}
 /**
  * Manages a pool of Tesseract workers with "Smart Affinity".
  *
@@ -31,6 +49,7 @@ class OcrSchedulerManager {
     MAX_WORKERS = 4;
     idleTimeout = 10000; // 10s default
     timeoutId = null;
+    isProcessing = false;
     constructor() { }
     /**
      * Returns the singleton instance of the manager.
@@ -65,103 +84,289 @@ class OcrSchedulerManager {
      * Performs OCR on an image using the smart worker pool.
      *
      * @param image - Image data (Buffer, string path, or Blob)
-     * @param config - OCR configuration (language, custom paths)
+     * @param config - OCR configuration (language, custom paths, timeouts, signal)
      * @returns Recognized text
      */
     async recognize(image, config) {
+        const signal = config?.abortSignal;
+        if (signal?.aborted) {
+            return Promise.reject((0, errorUtils_js_1.getAbortError)());
+        }
         return new Promise((resolve, reject) => {
-            // Update idle timeout if provided
-            if (config?.autoTerminateTimeout !== undefined) {
-                this.idleTimeout = config.autoTerminateTimeout;
+            // Update idle timeout if provided.
+            // Priority: timeout.autoTerminate (new) > autoTerminateTimeout (deprecated) > built-in default.
+            const effectiveAutoTerminate = config?.timeout?.autoTerminate ?? config?.autoTerminateTimeout;
+            if (effectiveAutoTerminate !== undefined) {
+                this.idleTimeout = effectiveAutoTerminate;
             }
             // Reset the inactivity timer every time a new job is requested
             this.resetIdleTimer();
+            let abortListener = null;
+            let finished = false;
+            let job;
+            const cleanResolve = (val) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (job)
+                    job.isFinished = true;
+                if (abortListener && signal) {
+                    signal.removeEventListener('abort', abortListener);
+                }
+                resolve(val);
+            };
+            const cleanReject = (err) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (job)
+                    job.isFinished = true;
+                if (abortListener && signal) {
+                    signal.removeEventListener('abort', abortListener);
+                }
+                reject(err);
+            };
+            // Priority: timeout.recognition (new) > 30 s default.
+            const recogTimeout = config?.timeout?.recognition ?? 30000;
+            // Create job
+            job = {
+                image,
+                config: config || {},
+                resolve: cleanResolve,
+                reject: cleanReject,
+                startTime: Date.now(),
+                timeoutMs: recogTimeout
+            };
+            if (signal) {
+                abortListener = () => {
+                    if (finished)
+                        return;
+                    const err = (0, errorUtils_js_1.getAbortError)();
+                    cleanReject(err);
+                    // 1. Remove job from queue if it hasn't run yet
+                    const idx = this.queue.indexOf(job);
+                    if (idx !== -1) {
+                        this.queue.splice(idx, 1);
+                    }
+                    // 2. Find if any worker is currently running this job and terminate/remove it
+                    const workerIndex = this.pool.findIndex(mw => mw.activeJob === job);
+                    if (workerIndex !== -1) {
+                        const managedWorker = this.pool[workerIndex];
+                        // Remove from pool immediately to prevent reuse
+                        this.pool.splice(workerIndex, 1);
+                        // Terminate the worker process
+                        try {
+                            managedWorker.worker.terminate();
+                        }
+                        catch (e) { }
+                        // Trigger queue processing for subsequent tasks
+                        this.processQueue();
+                    }
+                };
+                signal.addEventListener('abort', abortListener);
+            }
             // Add job to queue and trigger processing
-            this.queue.push({ image, config: config || {}, resolve, reject });
+            this.queue.push(job);
             this.processQueue();
         });
     }
     /**
      * Attempts to process the next job in the queue using an available worker.
+     * Designed to be race-free and support concurrent/parallel job execution.
      */
     async processQueue() {
-        if (this.queue.length === 0)
+        if (this.isProcessing)
             return;
-        const nextJob = this.queue[0];
-        const requestedLanguage = nextJob.config.language || 'eng';
-        // 1. Find an idle worker with the EXACT language affinity
-        let managed = this.pool.find(mw => !mw.isBusy && mw.language === requestedLanguage);
-        // 2. If not found and we have room, create a new worker
-        if (!managed && this.pool.length < this.MAX_WORKERS) {
-            try {
-                const { createWorker } = await import('tesseract.js');
-                const options = { logger: () => { } };
-                if (nextJob.config.workerPath)
-                    options.workerPath = nextJob.config.workerPath;
-                if (nextJob.config.corePath)
-                    options.corePath = nextJob.config.corePath;
-                if (nextJob.config.langPath)
-                    options.langPath = nextJob.config.langPath;
-                const worker = await createWorker(requestedLanguage, 1, options);
-                managed = {
-                    worker,
-                    language: requestedLanguage,
-                    lastUsed: Date.now(),
-                    isBusy: false
-                };
-                this.pool.push(managed);
+        this.isProcessing = true;
+        try {
+            while (this.queue.length > 0) {
+                const nextJob = this.queue[0];
+                if (nextJob.isFinished) {
+                    this.queue.shift();
+                    continue;
+                }
+                const requestedLanguage = nextJob.config.language || 'eng';
+                // 1. Find an idle worker with the EXACT language affinity
+                let managed = this.pool.find(mw => !mw.isBusy && mw.language === requestedLanguage);
+                // 2. If not found and we have room, create a new worker
+                if (!managed && this.pool.length < this.MAX_WORKERS) {
+                    const job = this.queue.shift();
+                    if (!job)
+                        continue;
+                    this.createAndRunWorker(job, requestedLanguage);
+                    continue;
+                }
+                // 3. If still not found and we are at capacity, find the LRU idle worker and re-initialize it
+                if (!managed) {
+                    const idleWorkers = this.pool.filter(mw => !mw.isBusy);
+                    if (idleWorkers.length > 0) {
+                        const job = this.queue.shift();
+                        if (!job)
+                            continue;
+                        managed = idleWorkers.reduce((prev, curr) => (prev.lastUsed < curr.lastUsed ? prev : curr));
+                        this.reinitializeAndRunWorker(managed, job, requestedLanguage);
+                        continue;
+                    }
+                }
+                // 4. If we have a worker ready, execute the job
+                if (managed) {
+                    const job = this.queue.shift();
+                    if (!job)
+                        continue;
+                    this.runWorker(managed, job);
+                    continue;
+                }
+                // No workers can be allocated right now (all busy and pool at capacity). Break work loop.
+                break;
             }
-            catch (err) {
-                const job = this.queue.shift();
-                job?.reject(err);
-                this.processQueue(); // Try next job
+        }
+        finally {
+            this.isProcessing = false;
+        }
+    }
+    /**
+     * Helper to dynamically instantiate a Tesseract worker, register it to the pool, and run the job.
+     */
+    async createAndRunWorker(job, requestedLanguage) {
+        // Priority: timeout.workerLoad (new) > 60 s default.
+        const loadTimeout = job.config.timeout?.workerLoad ?? 60000;
+        let managed = null;
+        try {
+            const { createWorker } = await import('tesseract.js');
+            const options = { logger: () => { } };
+            if (job.config.workerPath)
+                options.workerPath = job.config.workerPath;
+            if (job.config.corePath)
+                options.corePath = job.config.corePath;
+            if (job.config.langPath)
+                options.langPath = job.config.langPath;
+            const workerPromise = createWorker(requestedLanguage, 1, options);
+            // To prevent dangling worker threads on timeout or abort, we register a post-resolution hook
+            // that terminates the worker if the promise finishes after the timeout has fired or the job is finished.
+            let hasTimedOutOrAborted = false;
+            workerPromise.then(async (worker) => {
+                if (hasTimedOutOrAborted || job.isFinished) {
+                    try {
+                        await worker.terminate();
+                    }
+                    catch (e) { }
+                }
+            }, () => { });
+            const worker = loadTimeout > 0
+                ? await withTimeout(workerPromise, loadTimeout, `OCR worker initialization timed out after ${loadTimeout}ms`).catch(err => {
+                    hasTimedOutOrAborted = true;
+                    throw err;
+                })
+                : await workerPromise;
+            // If the job finished/aborted while loading, clean up the worker and skip execution.
+            if (job.isFinished) {
+                hasTimedOutOrAborted = true;
+                try {
+                    await worker.terminate();
+                }
+                catch (e) { }
+                this.processQueue();
                 return;
             }
+            managed = {
+                worker,
+                language: requestedLanguage,
+                lastUsed: Date.now(),
+                isBusy: false
+            };
+            this.pool.push(managed);
+            await this.runWorker(managed, job);
         }
-        // 3. If still not found and we are at capacity, find the LRU idle worker and re-initialize it
-        if (!managed) {
-            const idleWorkers = this.pool.filter(mw => !mw.isBusy);
-            if (idleWorkers.length > 0) {
-                // Find Least Recently Used idle worker
-                managed = idleWorkers.reduce((prev, curr) => (prev.lastUsed < curr.lastUsed ? prev : curr));
-                try {
-                    // Smart Re-initialization (v5 API)
-                    await managed.worker.reinitialize(requestedLanguage);
-                    managed.language = requestedLanguage;
+        catch (err) {
+            job.reject(err);
+            this.processQueue();
+        }
+    }
+    /**
+     * Helper to reinitialize an existing idle worker with a different language affinity and run the job.
+     */
+    async reinitializeAndRunWorker(managed, job, requestedLanguage) {
+        // Priority: timeout.workerLoad (new) > 60 s default.
+        const loadTimeout = job.config.timeout?.workerLoad ?? 60000;
+        managed.isBusy = true;
+        managed.lastUsed = Date.now();
+        managed.activeJob = job;
+        try {
+            const reinitPromise = managed.worker.reinitialize(requestedLanguage);
+            if (loadTimeout > 0) {
+                await withTimeout(reinitPromise, loadTimeout, `OCR worker re-initialization timed out after ${loadTimeout}ms`);
+            }
+            else {
+                await reinitPromise;
+            }
+            managed.language = requestedLanguage;
+            // If the job finished/aborted while reinitializing, clean up and skip execution.
+            if (job.isFinished) {
+                const index = this.pool.indexOf(managed);
+                if (index !== -1) {
+                    this.pool.splice(index, 1);
                 }
-                catch (err) {
-                    // If reinitialization fails, we might need to recreate it, but for simplicity 
-                    // we'll just fail this job and try another worker next time.
-                    const job = this.queue.shift();
-                    job?.reject(err);
-                    this.processQueue();
-                    return;
+                try {
+                    await managed.worker.terminate();
                 }
+                catch (e) { }
+                this.processQueue();
+                return;
             }
+            await this.runWorker(managed, job);
         }
-        // 4. If we have a worker ready, execute the job
-        if (managed) {
-            const job = this.queue.shift();
-            if (!job)
-                return;
-            managed.isBusy = true;
-            managed.lastUsed = Date.now();
+        catch (err) {
+            // Re-initialization failed/timed out, remove worker from pool and terminate
+            const index = this.pool.indexOf(managed);
+            if (index !== -1) {
+                this.pool.splice(index, 1);
+            }
             try {
-                const { data: { text } } = await managed.worker.recognize(job.image);
-                job.resolve(text);
+                await managed.worker.terminate();
             }
-            catch (err) {
-                job.reject(err);
+            catch (e) { }
+            job.reject(err);
+            this.processQueue();
+        }
+    }
+    /**
+     * Helper to execute OCR text recognition on the worker and return the results.
+     */
+    async runWorker(managed, job) {
+        // Priority: timeout.recognition (new) > 30 s default.
+        const recogTimeout = job.config.timeout?.recognition ?? 30000;
+        managed.isBusy = true;
+        managed.lastUsed = Date.now();
+        managed.activeJob = job;
+        try {
+            const recognizePromise = managed.worker.recognize(job.image);
+            const { data: { text } } = recogTimeout > 0
+                ? await withTimeout(recognizePromise, recogTimeout, `OCR recognition timed out after ${recogTimeout}ms`)
+                : await recognizePromise;
+            job.resolve(text);
+        }
+        catch (err) {
+            // If it timed out, terminate and remove worker to avoid reusing a stuck process
+            if (err.message?.includes('timed out')) {
+                const index = this.pool.indexOf(managed);
+                if (index !== -1) {
+                    this.pool.splice(index, 1);
+                }
+                try {
+                    await managed.worker.terminate();
+                }
+                catch (e) { }
             }
-            finally {
+            job.reject(err);
+        }
+        finally {
+            if (this.pool.includes(managed)) {
                 managed.isBusy = false;
+                managed.activeJob = undefined;
                 managed.lastUsed = Date.now();
-                // Check if there are more jobs waiting
-                this.processQueue();
             }
+            this.processQueue();
         }
-        // If no worker is available (all busy), the job stays in the queue 
-        // and will be picked up when a worker finishes.
     }
     /**
      * Terminates all workers in the pool and resets the state.

package/dist/utils/xmlUtils.d.ts

@@ -144,3 +144,11 @@ export declare const parseOfficeMetadata: (xmlContent: string) => OfficeMetadata
  * ```
  */
 export declare const parseOOXMLCustomProperties: (xmlContent: string) => Record<string, string | number | boolean | Date>;
+/**
+ * Decodes XML entities (standard named entities, decimal, and hexadecimal entities) in a string.
+ * Useful when parsing content with regular expressions instead of a full DOM parser.
+ *
+ * @param text - The XML-encoded string
+ * @returns The decoded string
+ */
+export declare const decodeXmlEntities: (text: string) => string;

package/dist/utils/xmlUtils.js

@@ -11,7 +11,7 @@
  * @module xmlUtils
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOOXMLCustomProperties = exports.parseOfficeMetadata = exports.getDirectChildren = exports.getAttribute = exports.getFirstElementByTagName = exports.getRawContent = exports.getSourceSubstring = exports.serializeXml = exports.getElementsByTagName = exports.parseXmlString = exports.isElement = void 0;
+exports.decodeXmlEntities = exports.parseOOXMLCustomProperties = exports.parseOfficeMetadata = exports.getDirectChildren = exports.getAttribute = exports.getFirstElementByTagName = exports.getRawContent = exports.getSourceSubstring = exports.serializeXml = exports.getElementsByTagName = exports.parseXmlString = exports.isElement = void 0;
 const xmldom_1 = require("@xmldom/xmldom");
 const dateUtils_js_1 = require("./dateUtils.js");
 /**
@@ -375,3 +375,35 @@ const parseOOXMLCustomProperties = (xmlContent) => {
     return result;
 };
 exports.parseOOXMLCustomProperties = parseOOXMLCustomProperties;
+/**
+ * Decodes XML entities (standard named entities, decimal, and hexadecimal entities) in a string.
+ * Useful when parsing content with regular expressions instead of a full DOM parser.
+ *
+ * @param text - The XML-encoded string
+ * @returns The decoded string
+ */
+const decodeXmlEntities = (text) => {
+    return text.replace(/&([^;]+);/g, (match, entity) => {
+        if (entity.startsWith('#')) {
+            if (entity[1] === 'x' || entity[1] === 'X') {
+                const hex = entity.slice(2);
+                const code = parseInt(hex, 16);
+                return !isNaN(code) ? String.fromCodePoint(code) : match;
+            }
+            else {
+                const dec = entity.slice(1);
+                const code = parseInt(dec, 10);
+                return !isNaN(code) ? String.fromCodePoint(code) : match;
+            }
+        }
+        switch (entity) {
+            case 'amp': return '&';
+            case 'lt': return '<';
+            case 'gt': return '>';
+            case 'quot': return '"';
+            case 'apos': return "'";
+            default: return match;
+        }
+    });
+};
+exports.decodeXmlEntities = decodeXmlEntities;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "officeparser",
-  "version": "7.0.2",
+  "version": "7.1.0",
   "description": "A robust, strictly-typed Node.js and Browser library for parsing office files (.docx, .pptx, .xlsx, .odt, .odp, .ods, .pdf, .rtf, .csv, .md, .html) and generating high-fidelity outputs in Markdown, HTML, CSV, RTF, and RAG-focused chunks.",
   "funding": "https://github.com/sponsors/harshankur",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "build:browser:types": "dts-bundle-generator --no-check -o dist/officeparser.browser.d.ts src/index.ts",
     "build:browser": "node build_browser.js && npm run sync:docs",
     "sync:versions": "node scripts/sync-pdfjs-versions.js",
-    "sync:docs": "mkdir -p docs/dist && cp dist/officeparser.browser.iife.js docs/dist/ && cp dist/officeparser.browser.mjs docs/dist/",
+    "sync:docs": "mkdir -p docs/dist && cp dist/officeparser.browser.iife.js docs/dist/ && cp dist/officeparser.browser.mjs docs/dist/ && mkdir -p docs/test/files && cp test/files/* docs/test/files/",
     "lint": "eslint src",
     "test": "npm run lint && npm run test:clean && npm run build && npm run test:license && npm run test:artifacts && npm run test:parser && npm run test:generator",
     "test:baseline": "npm run test:parser:baseline && npm run test:generator:baseline",
@@ -38,6 +38,7 @@
     "test:generator": "npx tsx test/generator/testOfficeGenerator.ts",
     "test:generator:baseline": "npx tsx test/generator/testOfficeGenerator.ts baseline",
     "test:artifacts": "npx tsx test/testShippingArtifacts.ts",
+    "test:visualizer": "node test/testVisualizer.js",
     "test:license": "npm run sbom && node scripts/validate-licenses.js",
     "test:clean": "rm -rf test/results test/generator/results test/generator/output test/parser/results test/parser/output",
     "clean": "rm -rf dist && npm run test:clean",