officeparser 6.0.7 → 6.1.1

package/dist/types.d.ts

@@ -1,3 +1,40 @@
+/**
+ * Configuration options for OCR.
+ */
+export interface OcrConfig {
+    /**
+     * Language for OCR.
+     * Default is 'eng'.
+     *
+     * You can provide multiple languages separated by a `+` sign (e.g., 'eng+fra' for English and French).
+     * The OCR engine will then attempt to recognize text in any of the specified languages.
+     *
+     * See the list of supported languages and their codes here:
+     * https://tesseract-ocr.github.io/tessdoc/Data-Files#data-files-for-version-400-november-29-2016
+     */
+    language?: string;
+    /**
+     * Path to the Tesseract worker script.
+     * Primarily used for offline/air-gapped environments.
+     */
+    workerPath?: string;
+    /**
+     * Path to the Tesseract core script.
+     * Primarily used for offline/air-gapped environments.
+     */
+    corePath?: string;
+    /**
+     * Path for Tesseract language files (traineddata).
+     * Primarily used for offline/air-gapped environments.
+     */
+    langPath?: string;
+    /**
+     * 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).
+     */
+    autoTerminateTimeout?: number;
+}
 /**
  * Configuration options for the OfficeParser.
  */
@@ -40,6 +77,7 @@ export interface OfficeParserConfig {
      */
     ocr?: boolean;
     /**
+     * @deprecated Use `ocrConfig.language` instead.
      * Language for OCR.
      * Default is 'eng'.
      *
@@ -50,14 +88,41 @@ export interface OfficeParserConfig {
      * https://tesseract-ocr.github.io/tessdoc/Data-Files#data-files-for-version-400-november-29-2016
      */
     ocrLanguage?: string;
+    /**
+     * Shared OCR configuration for worker pooling and offline support.
+     * If provided, `ocrLanguage` will be ignored in favor of `ocrConfig.language`.
+     */
+    ocrConfig?: OcrConfig;
+    /**
+     * Flag to serialize raw content (XML) as clean, formatted strings.
+     * Only relevant when `includeRawContent` is true.
+     * Default is true.
+     *
+     * If false, the parser will attempt to extract the original raw substring from the
+     * source document instead of re-serializing the DOM node.
+     */
+    serializeRawContent?: boolean;
+    /**
+     * Flag to preserve original XML whitespace and line endings when serializing.
+     * Only relevant when `includeRawContent` is true and `serializeRawContent` is true.
+     * Default is false.
+     */
+    preserveXmlWhitespace?: boolean;
     /**
      * The URL/path to the PDF.js worker script.
      *
      * **Mandatory** when using PDF parsing in browser environments to avoid worker configuration errors.
-     * If not provided, it defaults to `https://unpkg.com/pdfjs-dist@5.5.207/build/pdf.worker.min.mjs`.
+     * If not provided, it defaults to `https://unpkg.com/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs`.
      * You can override this with your own local path or a different CDN link.
      */
     pdfWorkerSrc?: string;
+    /**
+     * Flag to include break nodes in the AST.
+     * This is currently only supported for Word documents. (w:br nodes)
+     *
+     * Default is false
+     */
+    includeBreakNodes?: boolean;
 }
 /**
  * Supported file types for parsing.
@@ -66,7 +131,7 @@ export type SupportedFileType = 'docx' | 'pptx' | 'xlsx' | 'odt' | 'odp' | 'ods'
 /**
  * Types of content nodes in the AST.
  */
-export type OfficeContentNodeType = 'paragraph' | 'heading' | 'table' | 'list' | 'text' | 'image' | 'chart' | 'drawing' | 'slide' | 'note' | 'sheet' | 'row' | 'cell' | 'page';
+export type OfficeContentNodeType = 'paragraph' | 'heading' | 'table' | 'list' | 'text' | 'image' | 'chart' | 'drawing' | 'slide' | 'note' | 'sheet' | 'row' | 'cell' | 'page' | 'break';
 /**
  * Supported MIME types for attachments.
  */
@@ -169,6 +234,20 @@ export interface SheetMetadata {
     /** The style of the sheet. */
     style?: string;
 }
+/**
+ * Detailed indentation information for paragraphs and headings.
+ * Values are typically in twentieths of a point (twips) in OOXML.
+ */
+export interface IndentationMetadata {
+    /** Left indentation. */
+    left?: number;
+    /** Right indentation. */
+    right?: number;
+    /** First line indentation. */
+    firstLine?: number;
+    /** Hanging indentation. */
+    hanging?: number;
+}
 /**
  * Metadata for a heading.
  */
@@ -179,6 +258,8 @@ export interface HeadingMetadata {
     alignment?: 'left' | 'center' | 'right' | 'justify';
     /** The style of the heading. */
     style?: string;
+    /** Detailed indentation information. */
+    paragraphIndentation?: IndentationMetadata;
 }
 /**
  * Metadata for a paragraph.
@@ -188,6 +269,8 @@ export interface ParagraphMetadata {
     alignment?: 'left' | 'center' | 'right' | 'justify';
     /** The style of the paragraph. */
     style?: string;
+    /** Detailed indentation information. */
+    paragraphIndentation?: IndentationMetadata;
 }
 /**
  * Metadata for a list item.
@@ -203,6 +286,8 @@ export interface ListMetadata {
      * @example 0 for top-level items, 1 for first nested level
      */
     indentation: number;
+    /** Detailed indentation information. */
+    paragraphIndentation?: IndentationMetadata;
     /**
      * Text alignment of the list item.
      * @example 'left', 'center', 'right', 'justify'
@@ -329,10 +414,35 @@ export interface NoteMetadata {
      */
     noteId?: string;
 }
+/**
+ * Metadata for break nodes.
+ * Used in DOCX files to track line and page breaks.
+ */
+export interface BreakMetadata {
+    /**
+     * Type of break. The break type determines the next location where
+     * text shall be placed.
+     * - 'column': The next text will be placed in the next column.
+     * - 'page': The next text will be placed on the next page.
+     * - 'lastRenderedPage': The editing application has inserted a soft break on the last save.
+     * - 'textWrapping' (default, assumed when not specified): The next text will be placed on the next line.
+     * - 'carriageReturn': An explicit carriage return (w:cr) equivalent to a hard line break.
+     */
+    breakType: 'column' | 'page' | 'lastRenderedPage' | 'textWrapping' | 'carriageReturn';
+    /**
+     * Specifies the location which shall be used as the next available line when breakType
+     * has a value of 'textWrapping'. Should be ignored for other break types.
+     * - 'all': text wrapping break shall advance the text to the next line which spans the full width of the line
+     * - 'left': text wrapping break shall restart in next text region unblocked on the left
+     * - 'none': text wrapping break shall advance the text to the next line regardless of any floating objects
+     * - 'right': text wrapping break shall restart in next text region unblocked on the right
+     */
+    clear?: 'all' | 'left' | 'none' | 'right';
+}
 /**
  * Union type for content metadata.
  */
-export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | undefined;
+export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | undefined;
 /**
  * Represents a node in the document content tree.
  * This is the core building block of the parsed document structure.
@@ -540,6 +650,16 @@ export interface OfficeMetadata {
     formatting?: Partial<TextFormatting>;
     /** Style map for styles in the document. */
     styleMap?: Record<string, Partial<TextFormatting>>;
+    /**
+     * User-defined custom properties embedded in the document.
+     * Sources by format:
+     * - DOCX/XLSX/PPTX: `docProps/custom.xml` (Office custom document properties)
+     * - ODT/ODP/ODS: `meta:user-defined` elements in `meta.xml`
+     * - PDF: non-standard entries in the PDF Info dictionary
+     * RTF does not support custom properties; the `\info` group is not extracted.
+     * Values are typed as string, number, boolean, or Date where the source format provides type information.
+     */
+    customProperties?: Record<string, string | number | boolean | Date>;
 }
 /**
  * The Abstract Syntax Tree (AST) returned by the parser.

package/dist/utils/chartUtils.js

@@ -43,6 +43,8 @@ const extractOpenXmlChartData = (xmlBuffer) => {
     const xml = xmlBuffer.toString("utf8");
     const dom = (0, xmlUtils_1.parseXmlString)(xml);
     const root = dom.documentElement;
+    if (!root)
+        return { title: undefined, xAxisTitle: undefined, yAxisTitle: undefined, dataSets: [], labels: [], rawTexts: [] };
     const title = extractOpenXmlRichText(root, "c:title");
     // Axis titles
     let xAxisTitle = undefined;

package/dist/utils/dateUtils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Date Parsing Utilities
+ *
+ * Provides robust functions for parsing date strings from various office formats.
+ * Handles standard ISO dates, PDF-specific date formats, and malformed strings.
+ *
+ * @module dateUtils
+ */
+/**
+ * Parses a date string into a Date object.
+ * Handles standard ISO formats and falls back to native parsing.
+ * Returns undefined instead of "Invalid Date" if parsing fails.
+ *
+ * @param dateString - The date string to parse
+ * @returns Parsed Date object or undefined if parsing fails
+ */
+export declare function parseOfficeDate(dateString: string | undefined): Date | undefined;

package/dist/utils/dateUtils.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Date Parsing Utilities
+ *
+ * Provides robust functions for parsing date strings from various office formats.
+ * Handles standard ISO dates, PDF-specific date formats, and malformed strings.
+ *
+ * @module dateUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOfficeDate = parseOfficeDate;
+/**
+ * Parses a date string into a Date object.
+ * Handles standard ISO formats and falls back to native parsing.
+ * Returns undefined instead of "Invalid Date" if parsing fails.
+ *
+ * @param dateString - The date string to parse
+ * @returns Parsed Date object or undefined if parsing fails
+ */
+function parseOfficeDate(dateString) {
+    if (!dateString)
+        return undefined;
+    try {
+        // PDF-specific format detection: D:YYYYMMDDHHmmSSOHH'mm'
+        if (dateString.startsWith('D:')) {
+            return parsePdfDate(dateString);
+        }
+        const date = new Date(dateString);
+        return isNaN(date.getTime()) ? undefined : date;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Internal helper for PDF-specific date format: D:YYYYMMDDHHmmSSOHH'mm'
+ * @param dateString - The PDF date string
+ */
+function parsePdfDate(dateString) {
+    try {
+        // Remove "D:" prefix
+        let str = dateString.slice(2);
+        // Extract components: YYYYMMDDHHmmSS
+        const year = parseInt(str.slice(0, 4), 10);
+        const month = parseInt(str.slice(4, 6), 10) - 1; // 0-indexed
+        const day = parseInt(str.slice(6, 8), 10) || 1;
+        const hour = parseInt(str.slice(8, 10), 10) || 0;
+        const minute = parseInt(str.slice(10, 12), 10) || 0;
+        const second = parseInt(str.slice(12, 14), 10) || 0;
+        // Handle timezone if present
+        const tzMatch = str.slice(14).match(/([+-Z])(\d{2})'?(\d{2})?'?/);
+        if (tzMatch) {
+            if (tzMatch[1] === 'Z') {
+                return new Date(Date.UTC(year, month, day, hour, minute, second));
+            }
+            const tzSign = tzMatch[1] === '-' ? -1 : 1;
+            const tzHours = parseInt(tzMatch[2], 10) || 0;
+            const tzMinutes = parseInt(tzMatch[3], 10) || 0;
+            const offset = tzSign * (tzHours * 60 + tzMinutes);
+            // Create date in UTC and adjust for timezone
+            const utc = Date.UTC(year, month, day, hour, minute, second);
+            return new Date(utc - offset * 60000);
+        }
+        return new Date(year, month, day, hour, minute, second);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/envUtils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Environment detection and safe utility wrappers.
+ */
+/**
+ * Detect if we are running in a browser environment.
+ */
+export declare const isBrowser: boolean;
+/**
+ * Supported Node.js-only features that require explicit guarding for browser compatibility.
+ */
+export type NodeFeature = 'fs' | 'path-parsing' | 'pdf-worker-auto-resolution';
+/**
+ * Throws an error if attempted to use Node.js-specific features in the browser.
+ *
+ * @param feature - The Node.js feature being accessed
+ * @throws {Error} Clear error message directing browser users to use Buffers
+ */
+export declare function assertNode(feature: NodeFeature): void;
+/**
+ * Polyfills DOMMatrix if not available globally (required for Node.js < 20).
+ * This shim provides enough properties for pdfjs-dist 5.x to calculate
+ * text coordinates and transformations.
+ */
+export declare function ensureDomMatrix(): void;

package/dist/utils/envUtils.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Environment detection and safe utility wrappers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBrowser = void 0;
+exports.assertNode = assertNode;
+exports.ensureDomMatrix = ensureDomMatrix;
+/**
+ * Detect if we are running in a browser environment.
+ */
+exports.isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+/**
+ * Human-readable descriptions for Node-only features.
+ */
+const readableFeatures = {
+    'fs': 'direct file system access',
+    'path-parsing': 'parsing from file path string',
+    'pdf-worker-auto-resolution': 'automatic PDF worker resolution from node_modules'
+};
+/**
+ * Throws an error if attempted to use Node.js-specific features in the browser.
+ *
+ * @param feature - The Node.js feature being accessed
+ * @throws {Error} Clear error message directing browser users to use Buffers
+ */
+function assertNode(feature) {
+    if (exports.isBrowser) {
+        throw new Error(`officeparser: '${readableFeatures[feature]}' is not supported in the browser. Browser users must pass file content as Buffer or ArrayBuffer directly.`);
+    }
+}
+/**
+ * Polyfills DOMMatrix if not available globally (required for Node.js < 20).
+ * This shim provides enough properties for pdfjs-dist 5.x to calculate
+ * text coordinates and transformations.
+ */
+function ensureDomMatrix() {
+    if (typeof global !== 'undefined' && !global.DOMMatrix) {
+        global.DOMMatrix = class DOMMatrix {
+            a;
+            b;
+            c;
+            d;
+            e;
+            f;
+            constructor(init) {
+                if (Array.isArray(init) && init.length >= 6) {
+                    this.a = init[0];
+                    this.b = init[1];
+                    this.c = init[2];
+                    this.d = init[3];
+                    this.e = init[4];
+                    this.f = init[5];
+                }
+                else {
+                    this.a = this.d = 1;
+                    this.b = this.c = this.e = this.f = 0;
+                }
+            }
+            // Map standard matrix properties for compatibility
+            get m11() { return this.a; }
+            get m12() { return this.b; }
+            get m21() { return this.c; }
+            get m22() { return this.d; }
+            get m41() { return this.e; }
+            get m42() { return this.f; }
+        };
+    }
+}

package/dist/utils/moduleLoader.d.ts

@@ -7,10 +7,11 @@
  * This approach prevents TypeScript from transpiling dynamic import()
  * into require() when targeting CommonJS.
  */
+import type * as FileTypeModule from 'file-type' with { 'resolution-mode': 'import' };
 /**
  * Specialized loader for file-type
  */
-export declare function loadFileType(): Promise<typeof import('file-type')>;
+export declare function loadFileType(): Promise<typeof FileTypeModule>;
 /**
  * Specialized loader for pdfjs-dist
  */

package/dist/utils/moduleLoader.js

@@ -8,42 +8,10 @@
  * This approach prevents TypeScript from transpiling dynamic import()
  * into require() when targeting CommonJS.
  */
-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.loadFileType = loadFileType;
 exports.loadPdfJs = loadPdfJs;
+const envUtils_js_1 = require("./envUtils.js");
 /**
  * Dynamically loads an ESM module in a Node.js CJS context.
  *
@@ -59,18 +27,20 @@ async function loadNodeEsmModule(specifier) {
  * Specialized loader for file-type
  */
 async function loadFileType() {
-    if (typeof window === 'undefined') {
-        // Node.js path
+    if (!envUtils_js_1.isBrowser) {
+        // Node.js path: Use dynamic import wrapper for CJS compatibility
         return loadNodeEsmModule('file-type');
     }
-    // Browser path: esbuild handles standard dynamic import()
-    return Promise.resolve().then(() => __importStar(require('file-type')));
+    // Browser path: standard dynamic import() is handled by bundlers (e.g. esbuild/Vite)
+    return import('file-type');
 }
 /**
  * Specialized loader for pdfjs-dist
  */
 async function loadPdfJs() {
-    if (typeof window === 'undefined') {
+    if (!envUtils_js_1.isBrowser) {
+        // Ensure DOMMatrix polyfill for Node.js 18 support
+        (0, envUtils_js_1.ensureDomMatrix)();
         // Node.js environment: require legacy build for stability with ESM-only main
         try {
             return await loadNodeEsmModule('pdfjs-dist/legacy/build/pdf.mjs');
@@ -80,5 +50,5 @@ async function loadPdfJs() {
         }
     }
     // Browser environment: esbuild handles standard static-looking dynamic import()
-    return Promise.resolve().then(() => __importStar(require('pdfjs-dist')));
+    return import('pdfjs-dist');
 }

package/dist/utils/ocrUtils.d.ts

@@ -4,8 +4,12 @@
  * This module provides functions for extracting text from images using Tesseract.js.
  * Used when `config.ocr` is enabled to extract text from embedded images in documents.
  *
+ * Includes a worker pool via OcrSchedulerManager to improve performance when
+ * processing multiple images.
+ *
  * @module ocrUtils
  */
+import { OcrConfig } from '../types.js';
 /**
  * Performs Optical Character Recognition (OCR) on an image to extract text.
  *
@@ -13,26 +17,26 @@
  * This is useful for extracting text from screenshots, scanned documents,
  * charts with labels, or any image containing text.
  *
- * The function creates a new Tesseract worker, processes the image,
- * and properly terminates the worker to free resources.
+ * This function uses a shared worker pool to minimize initialization overhead.
  *
- * @param imageBuffer - The image data as a Node.js Buffer (PNG, JPEG, etc.)
- * @param language - The language code for OCR (default: 'eng' for English).
- *                   Supports ISO 639-2/T three-letter codes: 'eng', 'spa', 'fra', 'deu', etc.
- *                   Multiple languages can be combined with '+': 'eng+fra'
+ * @param image - The image data as a Buffer, file path, or Blob
+ * @param config - Optional configuration for language and custom worker paths
  * @returns A promise that resolves to the recognized text as a string
  * @throws {Error} If the image cannot be processed or Tesseract initialization fails
  *
  * @example
  * ```typescript
  * // Extract text from an English image
- * const text = await performOcr(imageBuffer, 'eng');
- * console.log(text); // "Annual Revenue: $1.2M"
- *
- * // Extract text from a multilingual image
- * const text = await performOcr(imageBuffer, 'eng+spa');
+ * const text = await performOcr(imageBuffer, { language: 'eng' });
  * ```
  *
  * @see https://github.com/naptha/tesseract.js for supported languages and options
  */
-export declare const performOcr: (image: Buffer | string, language?: string) => Promise<string>;
+export declare const performOcr: (image: Buffer | string, config?: OcrConfig) => Promise<string>;
+/**
+ * Terminates all OCR workers and cleans up resources.
+ *
+ * Should be called when the application is shutting down or OCR is no longer needed
+ * to prevent memory leaks and dangling worker processes.
+ */
+export declare const terminateOcr: () => Promise<void>;