officeparser 7.5.0 → 7.5.1

package/README.md

@@ -206,6 +206,15 @@ const ast = await officeParser.parseOffice(buffer);
 > const ast = await officeParser.parseOffice(markdownBuffer, { fileType: 'md' });
 > ```
 
+> [!NOTE]
+> **ZIP-backed formats are identified from inside the archive.** DOCX, XLSX, PPTX, ODT, ODS, ODP
+> and EPUB are all ZIP files, and telling them apart from the first bytes alone is unreliable for
+> archives written by streaming producers or holding very many parts. When the byte signature is
+> inconclusive, the archive is opened and the format is read from its own declaration
+> (`[Content_Types].xml`, or the `mimetype` entry), so these parse from a buffer without a hint.
+> Supplying `fileType` remains the fastest and most certain route: it decides which parser runs,
+> and for these formats no archive inspection is done at all.
+
 ### Cancellation with AbortSignal
 
 You can pass a standard `AbortSignal` (e.g. from an `AbortController`) to cancel an active parse operation. This is especially useful for setting request-level timeouts or canceling long-running parses (like large PDFs with OCR).
@@ -533,6 +542,34 @@ interface OfficeIssue {
 }
 ```
 
+Thrown errors carry the same object on `error.officeIssue`, so a failed parse is identified by
+the same stable `code` you would branch on for a warning, rather than by matching message text:
+
+```js
+try {
+    const ast = await officeParser.parseOffice(buffer, { fileType: 'docx' });
+} catch (err) {
+    switch (err.officeIssue?.code) {
+        case 'ZIP_NO_ENTRIES_FOUND':  // not a ZIP archive at all
+        case 'ZIP_TRUNCATED':         // cut off in transfer, entries incomplete
+        case 'REQUIRED_PART_MISSING': // readable ZIP, but not the format it claims
+            console.error('Unusable file:', err.officeIssue.message);
+            break;
+        default:
+            throw err;
+    }
+}
+```
+
+> [!IMPORTANT]
+> **A corrupt file throws; it does not parse as an empty document.** If an archive is not
+> readable, is truncated, or is missing the part its format requires (`word/document.xml`,
+> `xl/workbook.xml`, `ppt/presentation.xml`, ODF `content.xml`, the EPUB OPF), parsing rejects
+> with one of the codes above. An empty result therefore means the document really is empty.
+> Files that are legitimately empty still parse, and say so through `onWarning` /
+> `ast.warnings` (`NO_WORKSHEETS_FOUND` for a chartsheet-only workbook, `NO_SLIDES_FOUND` for a
+> presentation with no slides).
+
 ---
 
 ## Deep Dive: Document Components

package/dist/OfficeParser.js

@@ -55,6 +55,32 @@ const envUtils_js_1 = require("./utils/envUtils.js");
 const errorUtils_js_1 = require("./utils/errorUtils.js");
 const moduleLoader_js_1 = require("./utils/moduleLoader.js");
 const ocrUtils_js_1 = require("./utils/ocrUtils.js");
+const zipUtils_js_1 = require("./utils/zipUtils.js");
+/** What magic-byte sniffing reports for an archive it could not identify further. */
+const GENERIC_ZIP_EXTENSION = 'zip';
+/** The formats that are ZIP archives, and so cannot be contradicted by a bare `zip` result. */
+const ZIP_BACKED_FILE_TYPES = new Set(['docx', 'xlsx', 'pptx', 'odt', 'ods', 'odp', 'epub']);
+/**
+ * Upgrades a magic-byte result of `zip` (or none at all) into the specific office format the
+ * archive declares, by reading that declaration from inside the archive.
+ *
+ * Byte sniffing identifies an OOXML package by parsing `[Content_Types].xml`, but it walks the
+ * archive under fixed budgets and reports a plain `zip` when it runs out before finding that
+ * part. Since `zip` is not a format this library parses, a valid document then failed as an
+ * unsupported file type. Our own reader has no such budget, so it settles the question whenever
+ * sniffing is inconclusive.
+ *
+ * @param detected - What magic-byte sniffing reported, if anything
+ * @param buffer - The file content
+ * @param config - Resolved parser configuration, for its decompression limits
+ * @returns The resolved type, the original detection when nothing better is found, or undefined
+ */
+const resolveZipBackedType = async (detected, buffer, config) => {
+    if (detected && detected !== GENERIC_ZIP_EXTENSION)
+        return detected;
+    const resolved = await (0, zipUtils_js_1.detectOfficeTypeFromZip)(buffer, config.decompressionLimits ?? {});
+    return resolved ?? detected;
+};
 /**
  * Main parser class providing office document parsing functionality.
  *
@@ -168,15 +194,16 @@ class OfficeParser {
             // This matches v6 behavior and prevents crashes in older Node environments
             // where file-type 22.x might be incompatible.
             if (buffer.length > 0 && !ext) {
+                let detected;
                 try {
                     const { fileTypeFromBuffer } = await (0, moduleLoader_js_1.loadFileType)();
                     const type = await fileTypeFromBuffer(buffer);
                     if (type) {
-                        ext = type.ext;
+                        detected = type.ext;
                     }
                     else {
                         // If no extension could be detected and none was provided,
-                        // it might be a text-based format (csv, md, html) which 
+                        // it might be a text-based format (csv, md, html) which
                         // lack magic bytes. We'll let the switch default handle it.
                     }
                 }
@@ -184,16 +211,28 @@ class OfficeParser {
                     // Log warning but don't crash; the switch below will handle unsupported/missing ext
                     (0, errorUtils_js_1.logWarning)(types_js_1.OfficeWarningType.FILE_TYPE_DETECTION_FAILED, internalConfig, { error });
                 }
+                ext = await resolveZipBackedType(detected, buffer, internalConfig) ?? '';
             }
             else if (buffer.length > 0 && ext) {
-                // If extension is known, we can optionally verify it, but we wrap it 
+                // If extension is known, we can optionally verify it, but we wrap it
                 // in a try-catch to avoid breaking Node 18 if file-type fails to load.
                 try {
                     const { fileTypeFromBuffer } = await (0, moduleLoader_js_1.loadFileType)();
                     const type = await fileTypeFromBuffer(buffer);
-                    if (type && type.ext.toLowerCase() !== ext.toLowerCase()) {
+                    // A bare `zip` cannot contradict a caller who already said "this is a
+                    // docx", so there is nothing a closer look could add. Skipping it keeps an
+                    // explicit fileType the cheapest route, rather than making it pay for an
+                    // archive scan that exists only to decide whether to warn.
+                    const worthResolving = !(type?.ext === GENERIC_ZIP_EXTENSION && ZIP_BACKED_FILE_TYPES.has(ext.toLowerCase()));
+                    const detected = worthResolving
+                        ? await resolveZipBackedType(type?.ext, buffer, internalConfig)
+                        : type?.ext;
+                    // A bare `zip` says only that the bytes are an archive, which every format
+                    // on this path already is. Reporting it as a mismatch against the caller's
+                    // own extension is noise, so only a resolved format is worth comparing.
+                    if (detected && detected !== GENERIC_ZIP_EXTENSION && detected.toLowerCase() !== ext.toLowerCase()) {
                         // Mismatch found between authoritative extension and detected content
-                        (0, errorUtils_js_1.logWarning)(types_js_1.OfficeWarningType.BUFFER_TYPE_MISMATCH, internalConfig, { detected: type.ext, expected: ext });
+                        (0, errorUtils_js_1.logWarning)(types_js_1.OfficeWarningType.BUFFER_TYPE_MISMATCH, internalConfig, { detected, expected: ext });
                     }
                 }
                 catch (error) {
@@ -218,7 +257,16 @@ class OfficeParser {
                 case 'odt':
                 case 'odp':
                 case 'ods':
-                    result = await (0, OpenOfficeParser_js_1.parseOpenOffice)(buffer, internalConfig);
+                    // The three ODF types share one parser, which needs to know which of them
+                    // it is looking at. It normally reads that from the archive's mimetype
+                    // entry; passing the resolved type along gives it something accurate to
+                    // fall back on when that entry is missing.
+                    //
+                    // Overridden on a copy rather than on internalConfig: resolveParserConfig
+                    // returns an already-complete config by reference, so writing to it would
+                    // pin the caller's own object to this file's type and misroute every later
+                    // parse that reused it.
+                    result = await (0, OpenOfficeParser_js_1.parseOpenOffice)(buffer, { ...internalConfig, fileType: ext.toLowerCase() });
                     break;
                 case 'pdf':
                     result = await (0, PdfParser_js_1.parsePdf)(buffer, internalConfig);

package/dist/index.d.ts

@@ -51,10 +51,10 @@
 import { OfficeParser } from './OfficeParser.js';
 import { OfficeGenerator } from './OfficeGenerator.js';
 import { OfficeConverter } from './OfficeConverter.js';
-import { OfficeParserConfig, OfficeParserAST, OfficeContentNode, OfficeAttachment, OfficeMetadata, TextFormatting, SupportedFileType, OfficeContentNodeType, OfficeMimeType, SlideMetadata, SheetMetadata, HeadingMetadata, ListMetadata, CellMetadata, ImageMetadata, PageMetadata, ContentMetadata, BreakMetadata, GeneratorConfig, SupportedDestination, UniversalGeneratorFormat, ChunkingConfig, ChunkingStrategy, FixedSizeChunkingConfig, DocumentStructureChunkingConfig, SemanticChunkingConfig, OfficeChunk, OfficeConverterConfig, OfficeErrorType, OfficeWarningType, ConversionResult } from './types.js';
+import { OfficeParserConfig, OfficeParserAST, OfficeContentNode, OfficeAttachment, OfficeMetadata, TextFormatting, SupportedFileType, OfficeContentNodeType, OfficeMimeType, SlideMetadata, SheetMetadata, HeadingMetadata, ListMetadata, CellMetadata, ImageMetadata, PageMetadata, ContentMetadata, BreakMetadata, GeneratorConfig, SupportedDestination, UniversalGeneratorFormat, ChunkingConfig, ChunkingStrategy, FixedSizeChunkingConfig, DocumentStructureChunkingConfig, SemanticChunkingConfig, OfficeChunk, OfficeConverterConfig, OfficeErrorType, OfficeWarningType, OfficeError, ConversionResult } from './types.js';
 declare const parseOffice: typeof OfficeParser.parseOffice;
 declare const terminateOcr: typeof OfficeParser.terminateOcr;
 declare const convert: typeof OfficeConverter.convert;
 declare const generate: typeof OfficeGenerator.generate;
-export { OfficeParser, parseOffice, terminateOcr, OfficeParserConfig, OfficeParserAST, OfficeContentNode, OfficeAttachment, OfficeMetadata, TextFormatting, SupportedFileType, OfficeContentNodeType, OfficeMimeType, SlideMetadata, SheetMetadata, HeadingMetadata, ListMetadata, CellMetadata, ImageMetadata, PageMetadata, ContentMetadata, BreakMetadata, OfficeGenerator, GeneratorConfig, SupportedDestination, UniversalGeneratorFormat, ChunkingConfig, ChunkingStrategy, FixedSizeChunkingConfig, DocumentStructureChunkingConfig, SemanticChunkingConfig, OfficeChunk, OfficeConverter, OfficeConverterConfig, convert, generate, OfficeErrorType, OfficeWarningType, ConversionResult, };
+export { OfficeParser, parseOffice, terminateOcr, OfficeParserConfig, OfficeParserAST, OfficeContentNode, OfficeAttachment, OfficeMetadata, TextFormatting, SupportedFileType, OfficeContentNodeType, OfficeMimeType, SlideMetadata, SheetMetadata, HeadingMetadata, ListMetadata, CellMetadata, ImageMetadata, PageMetadata, ContentMetadata, BreakMetadata, OfficeGenerator, GeneratorConfig, SupportedDestination, UniversalGeneratorFormat, ChunkingConfig, ChunkingStrategy, FixedSizeChunkingConfig, DocumentStructureChunkingConfig, SemanticChunkingConfig, OfficeChunk, OfficeConverter, OfficeConverterConfig, convert, generate, OfficeErrorType, OfficeWarningType, OfficeError, ConversionResult, };
 export default OfficeParser;

package/dist/officeparser.browser.d.ts

@@ -41,6 +41,12 @@ export declare enum OfficeErrorType {
 	ZIP_ENTRY_INVALID_SIZE = "ZIP_ENTRY_INVALID_SIZE",
 	/** ZIP uncompressed size limit exceeded */
 	ZIP_SIZE_LIMIT_EXCEEDED = "ZIP_SIZE_LIMIT_EXCEEDED",
+	/** ZIP data yielded no readable entries (corrupt, truncated, or not a ZIP archive) */
+	ZIP_NO_ENTRIES_FOUND = "ZIP_NO_ENTRIES_FOUND",
+	/** ZIP data is truncated: the End of Central Directory record is absent */
+	ZIP_TRUNCATED = "ZIP_TRUNCATED",
+	/** A readable ZIP archive is missing the part its document format requires */
+	REQUIRED_PART_MISSING = "REQUIRED_PART_MISSING",
 	/** Document element/structure nesting exceeded the safe recursion depth */
 	MAX_NESTING_DEPTH_EXCEEDED = "MAX_NESTING_DEPTH_EXCEEDED",
 	/** Embedding call timed out */
@@ -90,7 +96,11 @@ export declare enum OfficeWarningType {
 	/** A metadata override could not be represented in the destination format's vocabulary */
 	METADATA_NOT_REPRESENTABLE = "METADATA_NOT_REPRESENTABLE",
 	/** A styleMap output.tag was not an allowed element name and was ignored */
-	INVALID_STYLE_MAP_TAG = "INVALID_STYLE_MAP_TAG"
+	INVALID_STYLE_MAP_TAG = "INVALID_STYLE_MAP_TAG",
+	/** A workbook archive contains no worksheet parts (chartsheet-only workbooks are legitimate) */
+	NO_WORKSHEETS_FOUND = "NO_WORKSHEETS_FOUND",
+	/** A presentation archive contains no slides (a zero-slide presentation is legitimate) */
+	NO_SLIDES_FOUND = "NO_SLIDES_FOUND"
 }
 /**
  * Consolidated timeout settings for OCR operations.
@@ -463,6 +473,29 @@ export interface OfficeIssue {
 	/** Optional additional context or original error object. */
 	details?: any;
 }
+/**
+ * An Error thrown by OfficeParser, carrying the structured issue that produced it.
+ *
+ * Catching code can branch on `error.officeIssue.code`, the same stable enum used for warnings,
+ * instead of matching against message text. Errors that originate outside the library (and
+ * `AbortError`, which is deliberately re-thrown untouched so cancellation stays detectable via
+ * `error.name`) do not carry this property, hence the optional marker.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     await parseOffice(buffer, { fileType: 'docx' });
+ * } catch (err) {
+ *     if ((err as OfficeError).officeIssue?.code === OfficeErrorType.REQUIRED_PART_MISSING) {
+ *         // the archive is readable, but it is not a docx
+ *     }
+ * }
+ * ```
+ */
+export interface OfficeError extends Error {
+	/** The structured issue this error was created from. */
+	officeIssue?: OfficeIssue;
+}
 /**
  * The result of a document conversion operation.
  */