officeparser 5.2.1 → 6.0.1

package/dist/utils/ocrUtils.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * OCR (Optical Character Recognition) Utilities
+ *
+ * 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.
+ *
+ * @module ocrUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.performOcr = void 0;
+const tesseract_js_1 = require("tesseract.js");
+/**
+ * Performs Optical Character Recognition (OCR) on an image to extract text.
+ *
+ * Uses Tesseract.js to recognize text in the provided image buffer.
+ * 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.
+ *
+ * @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'
+ * @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');
+ * ```
+ *
+ * @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
+    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;
+};
+exports.performOcr = performOcr;

package/dist/utils/xmlUtils.d.ts

@@ -0,0 +1,83 @@
+/**
+ * XML Parsing Utilities
+ *
+ * Provides helper functions for parsing and navigating XML documents.
+ * Used extensively by OOXML parsers (DOCX, XLSX, PPTX) and OpenOffice parsers (ODT, ODP, ODS).
+ *
+ * OOXML (Office Open XML) is an XML-based format used by Microsoft Office.
+ * Documents are ZIP archives containing multiple XML files describing structure, content, and formatting.
+ *
+ * @module xmlUtils
+ */
+import { OfficeMetadata } from '../types';
+/**
+ * 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
+ * @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;
+/**
+ * Gets all elements with a specific tag name and returns them as an array.
+ *
+ * This is a convenience wrapper around the DOM API's getElementsByTagName method
+ * that converts the HTMLCollection/NodeList to a proper JavaScript array for easier manipulation.
+ *
+ * @param element - The element or document to search within
+ * @param tagName - The tag name to search for (e.g., 'w:t', 'w:p', 'item')
+ * @returns An array of matching elements (empty array if none found)
+ * @example
+ * ```typescript
+ * const paragraphs = getElementsByTagName(doc, 'w:p');
+ * paragraphs.forEach(p => console.log(p.textContent));
+ * ```
+ */
+export declare const getElementsByTagName: (element: Element | Document, tagName: string) => Element[];
+/**
+ * Gets direct child elements with a specific tag name.
+ * Unlike getElementsByTagName, this does not search recursively.
+ *
+ * @param parent - The parent element
+ * @param tagName - The tag name to search for
+ * @returns An array of matching direct child elements
+ */
+export declare const getDirectChildren: (parent: Element, tagName: string) => Element[];
+/**
+ * Parses OOXML document metadata from the docProps/core.xml file.
+ *
+ * OOXML documents (DOCX, XLSX, PPTX) store metadata in a standard location:
+ * `docProps/core.xml` within the ZIP archive.
+ *
+ * This file follows the Dublin Core metadata standard with OOXML-specific extensions.
+ * Common metadata elements:
+ * - dc:title - Document title
+ * - dc:creator - Original author
+ * - cp:lastModifiedBy - User who last modified the document
+ * - dcterms:created - Creation timestamp
+ * - dcterms:modified - Last modification timestamp
+ *
+ * @param xmlContent - The raw XML content string from docProps/core.xml
+ * @returns An OfficeMetadata object with extracted properties (empty object if parsing fails)
+ * @example
+ * ```typescript
+ * const coreXml = files.find(f => f.path === 'docProps/core.xml').content.toString();
+ * const metadata = parseOfficeMetadata(coreXml);
+ *
+ * console.log(metadata.author); // "John Smith"
+ * console.log(metadata.title); // "Annual Report"
+ * console.log(metadata.created); // Date object
+ * ```
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085e39-c695-4f83-91e8-3f277bb4e111
+ */
+export declare const parseOfficeMetadata: (xmlContent: string) => OfficeMetadata;

package/dist/utils/xmlUtils.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * XML Parsing Utilities
+ *
+ * Provides helper functions for parsing and navigating XML documents.
+ * Used extensively by OOXML parsers (DOCX, XLSX, PPTX) and OpenOffice parsers (ODT, ODP, ODS).
+ *
+ * OOXML (Office Open XML) is an XML-based format used by Microsoft Office.
+ * Documents are ZIP archives containing multiple XML files describing structure, content, and formatting.
+ *
+ * @module xmlUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOfficeMetadata = exports.getDirectChildren = exports.getElementsByTagName = exports.parseXmlString = void 0;
+const xmldom_1 = require("@xmldom/xmldom");
+/**
+ * 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
+ * @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");
+};
+exports.parseXmlString = parseXmlString;
+/**
+ * Gets all elements with a specific tag name and returns them as an array.
+ *
+ * This is a convenience wrapper around the DOM API's getElementsByTagName method
+ * that converts the HTMLCollection/NodeList to a proper JavaScript array for easier manipulation.
+ *
+ * @param element - The element or document to search within
+ * @param tagName - The tag name to search for (e.g., 'w:t', 'w:p', 'item')
+ * @returns An array of matching elements (empty array if none found)
+ * @example
+ * ```typescript
+ * const paragraphs = getElementsByTagName(doc, 'w:p');
+ * paragraphs.forEach(p => console.log(p.textContent));
+ * ```
+ */
+const getElementsByTagName = (element, tagName) => {
+    return Array.from(element.getElementsByTagName(tagName));
+};
+exports.getElementsByTagName = getElementsByTagName;
+/**
+ * Gets direct child elements with a specific tag name.
+ * Unlike getElementsByTagName, this does not search recursively.
+ *
+ * @param parent - The parent element
+ * @param tagName - The tag name to search for
+ * @returns An array of matching direct child elements
+ */
+const getDirectChildren = (parent, tagName) => {
+    const result = [];
+    if (!parent.childNodes)
+        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
+            result.push(child);
+        }
+    }
+    return result;
+};
+exports.getDirectChildren = getDirectChildren;
+/**
+ * Parses OOXML document metadata from the docProps/core.xml file.
+ *
+ * OOXML documents (DOCX, XLSX, PPTX) store metadata in a standard location:
+ * `docProps/core.xml` within the ZIP archive.
+ *
+ * This file follows the Dublin Core metadata standard with OOXML-specific extensions.
+ * Common metadata elements:
+ * - dc:title - Document title
+ * - dc:creator - Original author
+ * - cp:lastModifiedBy - User who last modified the document
+ * - dcterms:created - Creation timestamp
+ * - dcterms:modified - Last modification timestamp
+ *
+ * @param xmlContent - The raw XML content string from docProps/core.xml
+ * @returns An OfficeMetadata object with extracted properties (empty object if parsing fails)
+ * @example
+ * ```typescript
+ * const coreXml = files.find(f => f.path === 'docProps/core.xml').content.toString();
+ * const metadata = parseOfficeMetadata(coreXml);
+ *
+ * console.log(metadata.author); // "John Smith"
+ * console.log(metadata.title); // "Annual Report"
+ * console.log(metadata.created); // Date object
+ * ```
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085e39-c695-4f83-91e8-3f277bb4e111
+ */
+const parseOfficeMetadata = (xmlContent) => {
+    // Step 1: Parse the XML content into a DOM document
+    const xml = (0, exports.parseXmlString)(xmlContent);
+    const metadata = {};
+    // Check for OOXML Core Properties
+    const coreProperties = (0, exports.getElementsByTagName)(xml, "cp:coreProperties")[0];
+    if (coreProperties) {
+        // Step 3: Extract title (Dublin Core element)
+        const title = (0, exports.getElementsByTagName)(coreProperties, "dc:title")[0];
+        if (title && title.textContent)
+            metadata.title = title.textContent;
+        // Step 4: Extract author/creator (Dublin Core element)
+        const author = (0, exports.getElementsByTagName)(coreProperties, "dc:creator")[0];
+        if (author && author.textContent)
+            metadata.author = author.textContent;
+        // Step 5: Extract last modifier (OOXML Core Properties element)
+        const lastModifiedBy = (0, exports.getElementsByTagName)(coreProperties, "cp:lastModifiedBy")[0];
+        if (lastModifiedBy && lastModifiedBy.textContent)
+            metadata.lastModifiedBy = lastModifiedBy.textContent;
+        // 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);
+        // 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);
+        return metadata;
+    }
+    // Check for ODF Meta
+    const officeMeta = (0, exports.getElementsByTagName)(xml, "office:meta")[0];
+    if (officeMeta) {
+        const title = (0, exports.getElementsByTagName)(officeMeta, "dc:title")[0];
+        if (title && title.textContent)
+            metadata.title = title.textContent;
+        const author = (0, exports.getElementsByTagName)(officeMeta, "dc:creator")[0];
+        if (author && author.textContent)
+            metadata.author = author.textContent;
+        const description = (0, exports.getElementsByTagName)(officeMeta, "dc:description")[0];
+        if (description && description.textContent)
+            metadata.description = description.textContent;
+        const subject = (0, exports.getElementsByTagName)(officeMeta, "dc:subject")[0];
+        if (subject && subject.textContent)
+            metadata.subject = subject.textContent;
+        const created = (0, exports.getElementsByTagName)(officeMeta, "meta:creation-date")[0];
+        if (created && created.textContent)
+            metadata.created = new Date(created.textContent);
+        const modified = (0, exports.getElementsByTagName)(officeMeta, "dc:date")[0];
+        if (modified && modified.textContent)
+            metadata.modified = new Date(modified.textContent);
+    }
+    return metadata;
+};
+exports.parseOfficeMetadata = parseOfficeMetadata;

package/dist/utils/zipUtils.d.ts

@@ -0,0 +1,74 @@
+/**
+ * ZIP Archive Extraction Utilities
+ *
+ * Provides functions for extracting files from ZIP archives.
+ * Essential for parsing OOXML (DOCX, XLSX, PPTX) and ODF (ODT, ODP, ODS) files,
+ * which are all ZIP archives containing XML and media files.
+ *
+ * Office File Structure:
+ * - DOCX: ZIP containing word/document.xml, word/styles.xml, word/media/*, etc.
+ * - XLSX: ZIP containing xl/workbook.xml, xl/worksheets/sheet1.xml, etc.
+ * - PPTX: ZIP containing ppt/slides/slide1.xml, ppt/media/*, etc.
+ * - ODF: Similar structure with content.xml, styles.xml, etc.
+ *
+ * @module zipUtils
+ */
+/// <reference types="node" />
+/**
+ * Represents a file extracted from a ZIP archive.
+ * Contains the file's path within the archive and its content as a Buffer.
+ */
+interface ZipFileContent {
+    /**
+     * The relative path of the file within the ZIP archive.
+     * @example "word/document.xml", "xl/worksheets/sheet1.xml", "ppt/slides/slide1.xml"
+     */
+    path: string;
+    /**
+     * The file content as a Node.js Buffer.
+     * Can be converted to string for XML files or used directly for binary files (images, etc.).
+     * @example Buffer containing XML text or binary image data
+     */
+    content: Buffer;
+}
+/**
+ * Extracts files from a ZIP archive with optional filtering.
+ *
+ * This function:
+ * 1. Opens the ZIP archive from a Buffer
+ * 2. Iterates through all entries in the archive
+ * 3. Applies a filter function to determine which files to extract
+ * 4. Extracts matching files and returns them as an array
+ *
+ * Uses lazy entry reading for better memory efficiency with large archives.
+ * Files are extracted asynchronously and collected into an array.
+ *
+ * @param zipInput - The ZIP file as a Node.js Buffer
+ * @param filterFn - A predicate function to determine which files to extract.
+ *                   Receives the filename and returns true to extract, false to skip.
+ * @returns A promise resolving to an array of extracted files
+ * @throws {Error} If the ZIP file cannot be opened or an entry cannot be read
+ *
+ * @example
+ * ```typescript
+ * // Extract only XML files from a DOCX
+ * const files = await extractFiles(docxBuffer, (fileName) => fileName.endsWith('.xml'));
+ *
+ * // Extract document.xml specifically
+ * const files = await extractFiles(docxBuffer, (fileName) =>
+ *   fileName === 'word/document.xml'
+ * );
+ *
+ * // Extract all files
+ * const allFiles = await extractFiles(zipBuffer, () => true);
+ *
+ * // Extract everything except media files
+ * const files = await extractFiles(zipBuffer, (fileName) =>
+ *   !fileName.startsWith('word/media/')
+ * );
+ * ```
+ *
+ * @see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT ZIP file format specification
+ */
+export declare const extractFiles: (zipInput: Buffer, filterFn: (fileName: string) => boolean) => Promise<ZipFileContent[]>;
+export {};

package/dist/utils/zipUtils.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * ZIP Archive Extraction Utilities
+ *
+ * Provides functions for extracting files from ZIP archives.
+ * Essential for parsing OOXML (DOCX, XLSX, PPTX) and ODF (ODT, ODP, ODS) files,
+ * which are all ZIP archives containing XML and media files.
+ *
+ * Office File Structure:
+ * - DOCX: ZIP containing word/document.xml, word/styles.xml, word/media/*, etc.
+ * - XLSX: ZIP containing xl/workbook.xml, xl/worksheets/sheet1.xml, etc.
+ * - PPTX: ZIP containing ppt/slides/slide1.xml, ppt/media/*, etc.
+ * - ODF: Similar structure with content.xml, styles.xml, etc.
+ *
+ * @module zipUtils
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFiles = void 0;
+const yauzl_1 = __importDefault(require("yauzl"));
+const concat_stream_1 = __importDefault(require("concat-stream"));
+/**
+ * Extracts files from a ZIP archive with optional filtering.
+ *
+ * This function:
+ * 1. Opens the ZIP archive from a Buffer
+ * 2. Iterates through all entries in the archive
+ * 3. Applies a filter function to determine which files to extract
+ * 4. Extracts matching files and returns them as an array
+ *
+ * Uses lazy entry reading for better memory efficiency with large archives.
+ * Files are extracted asynchronously and collected into an array.
+ *
+ * @param zipInput - The ZIP file as a Node.js Buffer
+ * @param filterFn - A predicate function to determine which files to extract.
+ *                   Receives the filename and returns true to extract, false to skip.
+ * @returns A promise resolving to an array of extracted files
+ * @throws {Error} If the ZIP file cannot be opened or an entry cannot be read
+ *
+ * @example
+ * ```typescript
+ * // Extract only XML files from a DOCX
+ * const files = await extractFiles(docxBuffer, (fileName) => fileName.endsWith('.xml'));
+ *
+ * // Extract document.xml specifically
+ * const files = await extractFiles(docxBuffer, (fileName) =>
+ *   fileName === 'word/document.xml'
+ * );
+ *
+ * // Extract all files
+ * const allFiles = await extractFiles(zipBuffer, () => true);
+ *
+ * // Extract everything except media files
+ * const files = await extractFiles(zipBuffer, (fileName) =>
+ *   !fileName.startsWith('word/media/')
+ * );
+ * ```
+ *
+ * @see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT ZIP file format specification
+ */
+const extractFiles = (zipInput, filterFn) => {
+    return new Promise((resolve, reject) => {
+        // Step 1: Open the ZIP archive from the buffer
+        // lazyEntries: true means we manually control when to read each entry (better memory usage)
+        yauzl_1.default.fromBuffer(zipInput, { lazyEntries: true }, (err, zipfile) => {
+            if (err)
+                return reject(err);
+            if (!zipfile)
+                return reject(new Error("Failed to open zip file"));
+            // Array to collect all extracted files
+            const extractedFiles = [];
+            // Step 2: Start reading the first entry
+            // This triggers the 'entry' event
+            zipfile.readEntry();
+            // Step 3: Handle each entry (file or directory) in the ZIP
+            zipfile.on('entry', (entry) => {
+                // Step 3a: Check if this file should be extracted using the filter function
+                if (filterFn(entry.fileName)) {
+                    // Step 3b: Open a read stream for this entry
+                    zipfile.openReadStream(entry, (err, readStream) => {
+                        if (err)
+                            return reject(err);
+                        if (!readStream)
+                            return reject(new Error("Failed to open read stream"));
+                        // Step 3c: Pipe the stream through concat to collect all data into a single Buffer
+                        // This is necessary because streams deliver data in chunks
+                        readStream.pipe((0, concat_stream_1.default)((data) => {
+                            // Step 3d: Add the extracted file to our results
+                            extractedFiles.push({
+                                path: entry.fileName,
+                                content: data
+                            });
+                            // Step 3e: Continue to the next entry
+                            zipfile.readEntry();
+                        }));
+                    });
+                }
+                else {
+                    // Step 3f: Skip this entry and move to the next one
+                    zipfile.readEntry();
+                }
+            });
+            // Step 4: All entries have been processed
+            zipfile.on('end', () => resolve(extractedFiles));
+            // Step 5: Handle any errors during extraction
+            zipfile.on('error', reject);
+        });
+    });
+};
+exports.extractFiles = extractFiles;

package/package.json

@@ -1,22 +1,32 @@
 {
   "name": "officeparser",
-  "version": "5.2.1",
-  "description": "A Node.js library to parse text out of any office file. Currently supports docx, pptx, xlsx, odt, odp, ods, pdf files.",
-  "main": "officeParser.js",
+  "version": "6.0.1",
+  "description": "A robust, strictly-typed Node.js and Browser library for parsing office files (.docx, .pptx, .xlsx, .odt, .odp, .ods, .pdf, .rtf) into structured AST with rich metadata, formatting, and attachment support.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "files": [
-    "officeParser.js",
-    "typings/officeParser.d.ts",
-    "pdfjs-dist-build/*"
+    "dist"
   ],
-  "types": "typings/officeParser.d.ts",
   "scripts": {
-    "test": "node test/testOfficeParser.js"
+    "build": "tsc && node build_browser.js && npm run sync:docs",
+    "build:node": "tsc",
+    "build:browser": "node build_browser.js && npm run sync:docs",
+    "sync:docs": "mkdir -p docs/dist && cp dist/officeparser.browser.js docs/dist/",
+    "test": "npm run test:clean && npm run build && npx tsx test/testOfficeParser.ts",
+    "test:clean": "rm -rf test/results",
+    "clean": "rm -rf dist && npm run test:clean",
+    "prepublishOnly": "npm run build",
+    "prepare": "husky"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/harshankur/officeParser.git"
   },
-  "bin": "officeParser.js",
+  "bin": "dist/index.js",
   "keywords": [
     "office",
     "docx",
@@ -26,15 +36,28 @@
     "odp",
     "ods",
     "pdf",
+    "rtf",
     "parser",
-    "text",
-    "extract text",
-    "document",
+    "text extraction",
+    "document parser",
     "word",
     "excel",
-    "worksheet",
     "powerpoint",
-    "slides"
+    "spreadsheet",
+    "presentation",
+    "slides",
+    "ast",
+    "ocr",
+    "typescript",
+    "browser",
+    "metadata",
+    "formatting",
+    "attachments",
+    "tesseract",
+    "pdf.js",
+    "structured-data",
+    "openoffice",
+    "libreoffice"
   ],
   "author": "Harsh Ankur",
   "license": "MIT",
@@ -46,8 +69,8 @@
     "@xmldom/xmldom": "^0.8.10",
     "concat-stream": "^2.0.0",
     "file-type": "^16.5.4",
-    "node-ensure": "^0.0.0",
-    "pdfjs-dist": "^5.3.31",
+    "pdfjs-dist": "5.4.530",
+    "tesseract.js": "^6.0.0",
     "yauzl": "^3.1.3"
   },
   "devDependencies": {
@@ -55,6 +78,10 @@
     "@types/node": "^18.16.1",
     "@types/xmldom": "^0.1.33",
     "@types/yauzl": "^2.10.3",
+    "esbuild": "^0.27.0",
+    "esbuild-plugin-polyfill-node": "^0.3.0",
+    "husky": "^9.1.7",
+    "tsx": "^4.21.0",
     "typescript": "^5.0.3"
   }
-}
+}