officeparser 6.0.7 → 6.1.1

package/dist/utils/ocrUtils.js

@@ -5,11 +5,176 @@
  * 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
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.performOcr = void 0;
-const tesseract_js_1 = require("tesseract.js");
+exports.terminateOcr = exports.performOcr = void 0;
+/**
+ * Manages a pool of Tesseract workers with "Smart Affinity".
+ *
+ * Instead of a simple scheduler, this manager allows workers to persist with
+ * a specific language affinity. If a new language is requested and the pool
+ * is at capacity, it re-initializes the Least Recently Used (LRU) idle worker
+ * rather than resetting the entire pool.
+ *
+ * Implements lazy loading of tesseract.js to ensure no background processes
+ * are spawned unless OCR is explicitly used.
+ */
+class OcrSchedulerManager {
+    static instance;
+    pool = [];
+    queue = [];
+    MAX_WORKERS = 4;
+    idleTimeout = 10000; // 10s default
+    timeoutId = null;
+    constructor() { }
+    /**
+     * Returns the singleton instance of the manager.
+     */
+    static getInstance() {
+        if (!OcrSchedulerManager.instance) {
+            OcrSchedulerManager.instance = new OcrSchedulerManager();
+        }
+        return OcrSchedulerManager.instance;
+    }
+    /**
+     * Checks if the singleton instance has been initialized.
+     */
+    static hasInstance() {
+        return !!OcrSchedulerManager.instance;
+    }
+    /**
+     * Resets the inactivity timer. If the timer reaches its duration,
+     * all workers are terminated automatically.
+     */
+    resetIdleTimer() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+        }
+        if (this.idleTimeout > 0) {
+            this.timeoutId = setTimeout(async () => {
+                await this.terminate();
+            }, this.idleTimeout);
+        }
+    }
+    /**
+     * 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)
+     * @returns Recognized text
+     */
+    async recognize(image, config) {
+        return new Promise((resolve, reject) => {
+            // Update idle timeout if provided
+            if (config?.autoTerminateTimeout !== undefined) {
+                this.idleTimeout = config.autoTerminateTimeout;
+            }
+            // Reset the inactivity timer every time a new job is requested
+            this.resetIdleTimer();
+            // Add job to queue and trigger processing
+            this.queue.push({ image, config: config || {}, resolve, reject });
+            this.processQueue();
+        });
+    }
+    /**
+     * Attempts to process the next job in the queue using an available worker.
+     */
+    async processQueue() {
+        if (this.queue.length === 0)
+            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);
+            }
+            catch (err) {
+                const job = this.queue.shift();
+                job?.reject(err);
+                this.processQueue(); // Try next job
+                return;
+            }
+        }
+        // 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) {
+                    // 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;
+                }
+            }
+        }
+        // 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();
+            try {
+                const { data: { text } } = await managed.worker.recognize(job.image);
+                job.resolve(text);
+            }
+            catch (err) {
+                job.reject(err);
+            }
+            finally {
+                managed.isBusy = false;
+                managed.lastUsed = Date.now();
+                // Check if there are more jobs waiting
+                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.
+     */
+    async terminate() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        const workersToTerminate = this.pool.map(mw => mw.worker.terminate());
+        await Promise.all(workersToTerminate);
+        this.pool = [];
+    }
+}
 /**
  * Performs Optical Character Recognition (OCR) on an image to extract text.
  *
@@ -17,45 +182,41 @@ const tesseract_js_1 = require("tesseract.js");
  * 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
  */
-const performOcr = async (image, language = 'eng') => {
-    // Step 1: Create a Tesseract worker with the specified language
-    // We pass 1 for OEM (LSTM) and a silent logger to suppress console output
-    const worker = await (0, tesseract_js_1.createWorker)(language, 1, {
-        logger: () => { }
-    });
-    // Step 2: Prepare image data
+const performOcr = async (image, config) => {
+    // Prepare image data
     let inputImage = image;
     // In browser environment, convert Buffer to Blob for better compatibility
     // @ts-ignore
     if (typeof window !== 'undefined' && typeof Blob !== 'undefined' && Buffer.isBuffer(image)) {
         inputImage = new Blob([image], { type: 'image/bmp' });
     }
-    // Step 3: Perform OCR
-    const ret = await worker.recognize(inputImage);
-    // Step 4: Terminate worker
-    await worker.terminate();
-    return ret.data.text;
+    return await OcrSchedulerManager.getInstance().recognize(inputImage, config);
 };
 exports.performOcr = performOcr;
+/**
+ * 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.
+ */
+const terminateOcr = async () => {
+    if (OcrSchedulerManager.hasInstance()) {
+        await OcrSchedulerManager.getInstance().terminate();
+    }
+};
+exports.terminateOcr = terminateOcr;

package/dist/utils/xmlUtils.d.ts

@@ -10,23 +10,22 @@
  * @module xmlUtils
  */
 import { OfficeMetadata } from '../types';
+/**
+ * Type guard for Element nodes.
+ */
+export declare const isElement: (node: Node) => node is Element;
 /**
  * Parses an XML string into a DOM Document object.
  *
  * Uses the @xmldom/xmldom library to parse XML strings in a Node.js environment.
- * This is necessary because Node.js doesn't have a built-in DOM parser like browsers do.
  *
  * @param xml - The XML content as a string
+ * @param options - Optional parser settings (e.g., enable locators for source mapping)
  * @returns A Document object that can be queried using standard DOM methods
- * @example
- * ```typescript
- * const xmlString = '<root><item>Hello</item></root>';
- * const doc = parseXmlString(xmlString);
- * const items = doc.getElementsByTagName('item');
- * console.log(items[0].textContent); // "Hello"
- * ```
  */
-export declare const parseXmlString: (xml: string) => Document;
+export declare const parseXmlString: (xml: string, options?: {
+    locator?: boolean;
+}) => Document;
 /**
  * Gets all elements with a specific tag name and returns them as an array.
  *
@@ -43,6 +42,54 @@ export declare const parseXmlString: (xml: string) => Document;
  * ```
  */
 export declare const getElementsByTagName: (element: Element | Document, tagName: string) => Element[];
+/**
+ * Serializes a DOM Node (Document, Element, etc.) back into an XML string.
+ * This is cross-platform and works in both Node.js and Browser environments.
+ *
+ * @param node - The DOM node to serialize
+ * @param options - Serialization options
+ * @returns The XML string representation
+ */
+export declare const serializeXml: (node: Node, options?: {
+    preserveWhitespace?: boolean;
+}) => string;
+/**
+ * Attempts to extract the original raw substring from the source XML for a given node.
+ * Requires the document to have been parsed with { locator: true }.
+ *
+ * @param node - The DOM node to extract source for
+ * @param sourceXml - The original XML source string
+ * @returns The raw XML substring, or undefined if it cannot be reliably determined
+ */
+export declare const getSourceSubstring: (node: any, sourceXml: string) => string | undefined;
+/**
+ * High-level helper to get raw content for a node based on OfficeParserConfig.
+ *
+ * @param node - The DOM node
+ * @param sourceXml - The original source XML string
+ * @param config - The parser configuration
+ * @returns The raw content string (serialized or original)
+ */
+export declare const getRawContent: (node: Node, sourceXml: string, config: {
+    serializeRawContent?: boolean;
+    preserveXmlWhitespace?: boolean;
+}) => string;
+/**
+ * Gets the first element with the specified tag name within a parent element.
+ *
+ * @param parent - The parent element or document to search within
+ * @param tagName - The tag name to search for
+ * @returns The first matching element, or undefined if none found
+ */
+export declare const getFirstElementByTagName: (parent: Element | Document, tagName: string) => Element | undefined;
+/**
+ * Gets the value of an attribute from an element.
+ *
+ * @param element - The element to get the attribute from
+ * @param attrName - The name of the attribute
+ * @returns The attribute value or undefined if not set
+ */
+export declare const getAttribute: (element: Element, attrName: string) => string | undefined;
 /**
  * Gets direct child elements with a specific tag name.
  * Unlike getElementsByTagName, this does not search recursively.
@@ -81,3 +128,27 @@ export declare const getDirectChildren: (parent: Element, tagName: string) => El
  * @see https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085e39-c695-4f83-91e8-3f277bb4e111
  */
 export declare const parseOfficeMetadata: (xmlContent: string) => OfficeMetadata;
+/**
+ * Parses OOXML custom document properties from `docProps/custom.xml`.
+ *
+ * Custom properties are user-defined key/value pairs that authors can attach to OOXML documents
+ * (DOCX, XLSX, PPTX). They are stored in `docProps/custom.xml` inside the ZIP archive.
+ *
+ * Property values are typed using the `vt:` namespace (docPropsVTypes):
+ * - `vt:lpwstr` / `vt:lpstr` / `vt:bstr` → string
+ * - `vt:bool` → boolean
+ * - `vt:i1`..`vt:i8`, `vt:int`, `vt:r4`, `vt:r8`, `vt:decimal` → number
+ * - `vt:filetime` / `vt:date` → Date
+ *
+ * @param xmlContent - Raw XML string from `docProps/custom.xml`
+ * @returns A record of property name → typed value (empty object if none found)
+ * @example
+ * ```typescript
+ * const customXml = files.find(f => f.path === 'docProps/custom.xml').content.toString();
+ * const props = parseOOXMLCustomProperties(customXml);
+ * console.log(props['Department']); // "Engineering"
+ * console.log(props['Priority']);   // 1  (number)
+ * console.log(props['Reviewed']);   // true (boolean)
+ * ```
+ */
+export declare const parseOOXMLCustomProperties: (xmlContent: string) => Record<string, string | number | boolean | Date>;

package/dist/utils/xmlUtils.js

@@ -11,27 +11,32 @@
  * @module xmlUtils
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOfficeMetadata = exports.getDirectChildren = exports.getElementsByTagName = exports.parseXmlString = void 0;
+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");
+/**
+ * Type guard for Element nodes.
+ */
+const isElement = (node) => {
+    return node.nodeType === 1;
+};
+exports.isElement = isElement;
 /**
  * Parses an XML string into a DOM Document object.
  *
  * Uses the @xmldom/xmldom library to parse XML strings in a Node.js environment.
- * This is necessary because Node.js doesn't have a built-in DOM parser like browsers do.
  *
  * @param xml - The XML content as a string
+ * @param options - Optional parser settings (e.g., enable locators for source mapping)
  * @returns A Document object that can be queried using standard DOM methods
- * @example
- * ```typescript
- * const xmlString = '<root><item>Hello</item></root>';
- * const doc = parseXmlString(xmlString);
- * const items = doc.getElementsByTagName('item');
- * console.log(items[0].textContent); // "Hello"
- * ```
  */
-const parseXmlString = (xml) => {
-    const parser = new xmldom_1.DOMParser();
-    return parser.parseFromString(xml, "text/xml");
+const parseXmlString = (xml, options = {}) => {
+    const parser = new xmldom_1.DOMParser(options);
+    // @xmldom/xmldom 0.9.x is strict: a UTF-8 BOM (U+FEFF) prepended to the
+    // XML string causes a fatalError because the XML declaration is no longer
+    // at position 0. Strip it before parsing.
+    const sanitized = xml.charCodeAt(0) === 0xFEFF ? xml.slice(1) : xml.trim();
+    return parser.parseFromString(sanitized, "text/xml");
 };
 exports.parseXmlString = parseXmlString;
 /**
@@ -50,9 +55,115 @@ exports.parseXmlString = parseXmlString;
  * ```
  */
 const getElementsByTagName = (element, tagName) => {
-    return Array.from(element.getElementsByTagName(tagName));
+    const results = Array.from(element.getElementsByTagName(tagName));
+    // Resilience: If prefixed tag (e.g., 'dc:title') not found, try local name (e.g., 'title')
+    if (results.length === 0 && tagName.includes(':')) {
+        const localName = tagName.split(':').pop();
+        return Array.from(element.getElementsByTagName(localName));
+    }
+    return results;
 };
 exports.getElementsByTagName = getElementsByTagName;
+/**
+ * Serializes a DOM Node (Document, Element, etc.) back into an XML string.
+ * This is cross-platform and works in both Node.js and Browser environments.
+ *
+ * @param node - The DOM node to serialize
+ * @param options - Serialization options
+ * @returns The XML string representation
+ */
+const serializeXml = (node, options = {}) => {
+    // Note: xmldom's XMLSerializer doesn't natively support a 'pretty' or 'preserve' 
+    // flag in a way that matches all user expectations, but it defaults to 
+    // preserving structure. Formatting (indentation) is usually handled by the 
+    // parser's initial whitespace handling.
+    // @ts-ignore - xmldom's Node is compatible with the global Node interface
+    return new xmldom_1.XMLSerializer().serializeToString(node);
+};
+exports.serializeXml = serializeXml;
+/**
+ * Attempts to extract the original raw substring from the source XML for a given node.
+ * Requires the document to have been parsed with { locator: true }.
+ *
+ * @param node - The DOM node to extract source for
+ * @param sourceXml - The original XML source string
+ * @returns The raw XML substring, or undefined if it cannot be reliably determined
+ */
+const getSourceSubstring = (node, sourceXml) => {
+    if (!node || typeof node.lineNumber !== 'number' || typeof node.columnNumber !== 'number') {
+        return undefined;
+    }
+    // Convert line/column to absolute index
+    const lines = sourceXml.split('\n');
+    let startIdx = 0;
+    for (let i = 0; i < node.lineNumber - 1; i++) {
+        startIdx += lines[i].length + 1; // +1 for newline
+    }
+    startIdx += node.columnNumber - 1;
+    // To find the end of the node, we look for the closing tag.
+    // This is a heuristic approach that works well for simple structured nodes (p, tbl, etc.)
+    // but might be complex for overlapping namespaces or malformed XML.
+    if ((0, exports.isElement)(node)) {
+        const tagName = node.tagName;
+        const closingTag = `</${tagName}>`;
+        const endIdx = sourceXml.indexOf(closingTag, startIdx);
+        if (endIdx !== -1) {
+            return sourceXml.substring(startIdx, endIdx + closingTag.length);
+        }
+        // Self-closing tag handling (e.g., <w:p/>)
+        const selfClosingEnd = sourceXml.indexOf('/>', startIdx);
+        const nextOpenTag = sourceXml.indexOf('<', startIdx + 1);
+        if (selfClosingEnd !== -1 && (nextOpenTag === -1 || selfClosingEnd < nextOpenTag)) {
+            return sourceXml.substring(startIdx, selfClosingEnd + 2);
+        }
+    }
+    return undefined;
+};
+exports.getSourceSubstring = getSourceSubstring;
+/**
+ * High-level helper to get raw content for a node based on OfficeParserConfig.
+ *
+ * @param node - The DOM node
+ * @param sourceXml - The original source XML string
+ * @param config - The parser configuration
+ * @returns The raw content string (serialized or original)
+ */
+const getRawContent = (node, sourceXml, config) => {
+    if (config.serializeRawContent === false) {
+        const original = (0, exports.getSourceSubstring)(node, sourceXml);
+        if (original)
+            return original;
+    }
+    return (0, exports.serializeXml)(node, { preserveWhitespace: config.preserveXmlWhitespace });
+};
+exports.getRawContent = getRawContent;
+/**
+ * Gets the first element with the specified tag name within a parent element.
+ *
+ * @param parent - The parent element or document to search within
+ * @param tagName - The tag name to search for
+ * @returns The first matching element, or undefined if none found
+ */
+const getFirstElementByTagName = (parent, tagName) => {
+    const elements = parent.getElementsByTagName(tagName);
+    if (elements && elements.length > 0) {
+        return elements[0];
+    }
+    return undefined;
+};
+exports.getFirstElementByTagName = getFirstElementByTagName;
+/**
+ * Gets the value of an attribute from an element.
+ *
+ * @param element - The element to get the attribute from
+ * @param attrName - The name of the attribute
+ * @returns The attribute value or undefined if not set
+ */
+const getAttribute = (element, attrName) => {
+    const attr = element.getAttribute(attrName);
+    return attr !== null ? attr : undefined;
+};
+exports.getAttribute = getAttribute;
 /**
  * Gets direct child elements with a specific tag name.
  * Unlike getElementsByTagName, this does not search recursively.
@@ -67,7 +178,7 @@ const getDirectChildren = (parent, tagName) => {
         return result;
     for (let i = 0; i < parent.childNodes.length; i++) {
         const child = parent.childNodes[i];
-        if (child.nodeType === 1 && child.tagName === tagName) { // 1 = ELEMENT_NODE
+        if ((0, exports.isElement)(child) && child.tagName === tagName) {
             result.push(child);
         }
     }
@@ -124,11 +235,18 @@ const parseOfficeMetadata = (xmlContent) => {
         // Step 6: Extract creation date (Dublin Core Terms element)
         const created = (0, exports.getElementsByTagName)(coreProperties, "dcterms:created")[0];
         if (created && created.textContent)
-            metadata.created = new Date(created.textContent);
+            metadata.created = (0, dateUtils_js_1.parseOfficeDate)(created.textContent);
         // Step 7: Extract last modification date (Dublin Core Terms element)
         const modified = (0, exports.getElementsByTagName)(coreProperties, "dcterms:modified")[0];
         if (modified && modified.textContent)
-            metadata.modified = new Date(modified.textContent);
+            metadata.modified = (0, dateUtils_js_1.parseOfficeDate)(modified.textContent);
+        // Step 8: Extract description and subject (Dublin Core elements)
+        const description = (0, exports.getElementsByTagName)(coreProperties, "dc:description")[0];
+        if (description && description.textContent)
+            metadata.description = description.textContent;
+        const subject = (0, exports.getElementsByTagName)(coreProperties, "dc:subject")[0];
+        if (subject && subject.textContent)
+            metadata.subject = subject.textContent;
         return metadata;
     }
     // Check for ODF Meta
@@ -148,11 +266,111 @@ const parseOfficeMetadata = (xmlContent) => {
             metadata.subject = subject.textContent;
         const created = (0, exports.getElementsByTagName)(officeMeta, "meta:creation-date")[0];
         if (created && created.textContent)
-            metadata.created = new Date(created.textContent);
+            metadata.created = (0, dateUtils_js_1.parseOfficeDate)(created.textContent);
         const modified = (0, exports.getElementsByTagName)(officeMeta, "dc:date")[0];
         if (modified && modified.textContent)
-            metadata.modified = new Date(modified.textContent);
+            metadata.modified = (0, dateUtils_js_1.parseOfficeDate)(modified.textContent);
+        // Extract user-defined custom properties (meta:user-defined)
+        const userDefined = (0, exports.getElementsByTagName)(officeMeta, "meta:user-defined");
+        if (userDefined.length > 0) {
+            const customProperties = {};
+            for (const el of userDefined) {
+                const name = el.getAttribute("meta:name");
+                if (!name || !el.textContent)
+                    continue;
+                const valueType = el.getAttribute("meta:value-type") || "string";
+                const raw = el.textContent;
+                if (valueType === "boolean") {
+                    customProperties[name] = raw.toLowerCase() === "true";
+                }
+                else if (valueType === "float") {
+                    const num = Number(raw);
+                    if (!isNaN(num))
+                        customProperties[name] = num;
+                }
+                else if (valueType === "date" || valueType === "time") {
+                    const date = (0, dateUtils_js_1.parseOfficeDate)(raw);
+                    if (date)
+                        customProperties[name] = date;
+                    else
+                        customProperties[name] = raw;
+                }
+                else {
+                    customProperties[name] = raw;
+                }
+            }
+            if (Object.keys(customProperties).length > 0) {
+                metadata.customProperties = customProperties;
+            }
+        }
     }
     return metadata;
 };
 exports.parseOfficeMetadata = parseOfficeMetadata;
+/**
+ * Parses OOXML custom document properties from `docProps/custom.xml`.
+ *
+ * Custom properties are user-defined key/value pairs that authors can attach to OOXML documents
+ * (DOCX, XLSX, PPTX). They are stored in `docProps/custom.xml` inside the ZIP archive.
+ *
+ * Property values are typed using the `vt:` namespace (docPropsVTypes):
+ * - `vt:lpwstr` / `vt:lpstr` / `vt:bstr` → string
+ * - `vt:bool` → boolean
+ * - `vt:i1`..`vt:i8`, `vt:int`, `vt:r4`, `vt:r8`, `vt:decimal` → number
+ * - `vt:filetime` / `vt:date` → Date
+ *
+ * @param xmlContent - Raw XML string from `docProps/custom.xml`
+ * @returns A record of property name → typed value (empty object if none found)
+ * @example
+ * ```typescript
+ * const customXml = files.find(f => f.path === 'docProps/custom.xml').content.toString();
+ * const props = parseOOXMLCustomProperties(customXml);
+ * console.log(props['Department']); // "Engineering"
+ * console.log(props['Priority']);   // 1  (number)
+ * console.log(props['Reviewed']);   // true (boolean)
+ * ```
+ */
+const parseOOXMLCustomProperties = (xmlContent) => {
+    const xml = (0, exports.parseXmlString)(xmlContent);
+    const result = {};
+    const properties = (0, exports.getElementsByTagName)(xml, "property");
+    for (const prop of properties) {
+        const name = prop.getAttribute("name");
+        if (!name)
+            continue;
+        // The value is the first child element (typed using vt: namespace)
+        for (let i = 0; i < prop.childNodes.length; i++) {
+            const child = prop.childNodes[i];
+            if (child.nodeType !== 1)
+                continue; // skip non-elements
+            const el = child;
+            const tag = el.tagName || '';
+            const text = el.textContent || '';
+            if (/vt:lpwstr|vt:lpstr|vt:bstr/.test(tag)) {
+                result[name] = text;
+            }
+            else if (/vt:bool/.test(tag)) {
+                result[name] = text.toLowerCase() === 'true';
+            }
+            else if (/vt:(i[1248]|ui[1248]|int|uint|r4|r8|decimal)/.test(tag)) {
+                const num = Number(text);
+                if (!isNaN(num))
+                    result[name] = num;
+            }
+            else if (/vt:filetime|vt:date/.test(tag)) {
+                const date = (0, dateUtils_js_1.parseOfficeDate)(text);
+                if (date)
+                    result[name] = date;
+                else
+                    result[name] = text;
+            }
+            else if (text) {
+                // Fallback: store as string for any other vt: type
+                result[name] = text;
+            }
+            break; // only one value element per property
+        }
+    }
+    return result;
+};
+exports.parseOOXMLCustomProperties = parseOOXMLCustomProperties;