officeparser 7.5.0 → 7.5.1

package/dist/utils/configUtils.js

@@ -83,19 +83,33 @@ function isFullParserConfig(config) {
 /**
  * Resolves a full parser configuration by merging defaults and user-provided overrides.
  *
+ * The returned object always belongs solely to the caller of this function. That matters
+ * because a parse installs per-call state on the config it is handed, such as the collector
+ * that gathers warnings for one document's `ast.warnings`. Returning the caller's own object
+ * would attach that state to an object they may reuse, so a second parse would append its
+ * warnings to the first document's already-returned AST, and each parse would retain the
+ * previous one's state for as long as the config lived.
+ *
+ * Only the configuration containers are copied. Callbacks and `abortSignal` keep their
+ * identity, since a copy of an `AbortSignal` would no longer be tied to its controller.
+ *
  * @param userConfig - Optional configuration provided by the user
- * @returns A fully populated configuration object
+ * @returns A fully populated configuration object, owned by the caller
  */
 function resolveParserConfig(userConfig) {
     if (isFullParserConfig(userConfig)) {
-        if (!userConfig.decompressionLimits) {
-            userConfig.decompressionLimits = {
-                maxUncompressedBytes: 512 * 1024 * 1024,
-                maxZipEntries: 10000,
-                maxTableCells: 1000000,
-            };
+        const resolved = { ...userConfig };
+        resolved.ocrConfig = { ...userConfig.ocrConfig };
+        if (userConfig.ocrConfig?.timeout) {
+            resolved.ocrConfig.timeout = { ...userConfig.ocrConfig.timeout };
+        }
+        resolved.decompressionLimits = {
+            ...(userConfig.decompressionLimits ?? defaults_js_1.DEFAULT_OFFICE_PARSER_CONFIG.decompressionLimits)
+        };
+        if (userConfig.htmlParserConfig) {
+            resolved.htmlParserConfig = { ...userConfig.htmlParserConfig };
         }
-        return userConfig;
+        return resolved;
     }
     // 1. Start with full defaults (deep cloned)
     const config = deepClone(defaults_js_1.DEFAULT_OFFICE_PARSER_CONFIG);
@@ -141,21 +155,52 @@ function resolveParserConfig(userConfig) {
     }
     return config;
 }
+/** The per-destination and metadata sub-objects a generator config groups its settings into. */
+const GENERATOR_CONFIG_CONTAINERS = [
+    'metadataOverrides', 'htmlConfig', 'mdConfig', 'pdfConfig',
+    'csvConfig', 'textConfig', 'rtfConfig', 'chunksConfig',
+];
+/**
+ * Copies a generator config's containers so writes during generation cannot reach the caller.
+ *
+ * One level is enough: the containers are what generation writes to. Everything else is copied
+ * by reference on purpose, since callbacks, `styleMap` and `abortSignal` are values whose
+ * identity matters, and a duplicated `AbortSignal` would no longer be tied to its controller.
+ *
+ * @param source - The caller's configuration
+ * @returns An equivalent configuration owned by us
+ */
+function copyGeneratorConfigContainers(source) {
+    const copy = { ...source };
+    for (const key of GENERATOR_CONFIG_CONTAINERS) {
+        const container = source[key];
+        if (container && typeof container === 'object')
+            copy[key] = { ...container };
+    }
+    return copy;
+}
 /**
  * Resolves a full, destination-specific configuration by merging defaults,
  * AST-level settings, and user-provided overrides.
  *
+ * As with {@link resolveParserConfig}, the returned object belongs solely to the caller of this
+ * function, so that per-run normalization cannot edit a config the caller still holds.
+ *
  * @param destination - The target format
  * @param userConfig - Optional configuration provided by the user
  * @param astConfig - Optional configuration from the source AST (for inheritance)
- * @returns A fully populated configuration object
+ * @returns A fully populated configuration object, owned by the caller
  */
 function resolveGeneratorConfig(destination, astConfig, userConfig) {
-    // If it's already a full config and we don't need to merge AST config, return it as is.
-    // We assume FullGeneratorConfig is already "safe" (references resolved).
+    // Already complete, so nothing to merge. Still copied rather than handed straight back, for
+    // the same reason as resolveParserConfig: generation writes to the config it is given. The
+    // width check below normalizes an invalid `containerWidth` to 'auto', and doing that to the
+    // caller's own object both edits a value they still hold and silences the warning on every
+    // later run, so the same config would report a problem once and then appear clean.
     if (isFullGeneratorConfig(userConfig) && !astConfig) {
-        validateHtmlConfigWidth(userConfig.htmlConfig, userConfig);
-        return userConfig;
+        const resolved = copyGeneratorConfigContainers(userConfig);
+        validateHtmlConfigWidth(resolved.htmlConfig, resolved);
+        return resolved;
     }
     // 1. Start with full defaults (deep cloned to avoid reference sharing)
     const config = deepClone(defaults_js_1.DEFAULT_GENERATOR_CONFIG);

package/dist/utils/errorUtils.d.ts

@@ -5,7 +5,7 @@
  * It defines standard error types, messages, and handling logic to ensure
  * consistent error reporting across all parsers and the main entry point.
  */
-import { OfficeErrorType, OfficeParserConfig, OfficeWarningType } from '../types.js';
+import { OfficeError, OfficeErrorType, OfficeParserConfig, OfficeWarningType } from '../types.js';
 /**
  * Creates a formatted warning message for a specific warning type.
  *
@@ -22,11 +22,17 @@ export declare const getWarningMessage: (type: OfficeWarningType, info?: any) =>
  * @param info - Optional additional information
  * @returns The Error object to be thrown
  */
-export declare const getOfficeError: (type: OfficeErrorType, config?: OfficeParserConfig, info?: any) => Error;
+export declare const getOfficeError: (type: OfficeErrorType, config?: OfficeParserConfig, info?: any) => OfficeError;
 /**
  * Wraps an existing error with OfficeParser context and performs corruption detection.
  * Optionally logs the error to console.
  *
+ * An error already built by {@link getOfficeError} is returned untouched: it carries an
+ * `officeIssue`, meaning it has been reported once and already bears the `[OfficeParser]: `
+ * header. Re-wrapping it would report the same issue a second time, prepend a second header,
+ * and flatten its specific error code to `FILE_CORRUPTED`. This is a marker check on the error
+ * object rather than a test against its message text, so it stays independent of wording.
+ *
  * **Important**: Do NOT pass AbortErrors to this function. AbortErrors (err.name === 'AbortError')
  * represent deliberate user cancellation and must be re-thrown as-is from the catch block so that
  * callers can reliably detect them via `err.name === 'AbortError'` or `err instanceof DOMException`.

package/dist/utils/errorUtils.js

@@ -11,6 +11,11 @@ exports.checkAbortSignal = exports.getAbortError = exports.logWarning = exports.
 const types_js_1 = require("../types.js");
 /** Error header prefix for all error messages */
 const ERRORHEADER = "[OfficeParser]: ";
+// `OfficeError` (the public shape callers catch) lives in types.ts alongside `OfficeIssue`.
+// Every error built by getOfficeError is branded with its issue, which serves two purposes:
+// consumers branch on `err.officeIssue.code` instead of matching message text, and
+// getWrappedError recognizes an error it has already reported and prefixed, so it neither
+// reports it twice nor prepends a second header.
 /**
  * Lookup table for error messages.
  * Some entries are functions that take parameters to build dynamic messages.
@@ -34,6 +39,9 @@ const ERROR_MESSAGES = {
     [types_js_1.OfficeErrorType.ZIP_ENTRY_COUNT_LIMIT_EXCEEDED]: (limit) => `ZIP entry count exceeds limit (${limit})`,
     [types_js_1.OfficeErrorType.ZIP_ENTRY_INVALID_SIZE]: `ZIP entry missing a valid declared size`,
     [types_js_1.OfficeErrorType.ZIP_SIZE_LIMIT_EXCEEDED]: (limit) => `ZIP uncompressed size limit exceeded (${limit} bytes)`,
+    [types_js_1.OfficeErrorType.ZIP_NO_ENTRIES_FOUND]: `No readable entries found in ZIP data. The input is corrupt, truncated, or not a ZIP archive: every ZIP-based document format requires at least one entry.`,
+    [types_js_1.OfficeErrorType.ZIP_TRUNCATED]: `Malformed ZIP data: no End of Central Directory record was found at the end of the input. Either the file was cut off during download or transfer, or extra data follows the archive; in both cases the entries recovered from it cannot be trusted to be the whole document.`,
+    [types_js_1.OfficeErrorType.REQUIRED_PART_MISSING]: (info) => `Your ${info.fileType} file is a readable ZIP archive but is missing its required '${info.part}' part, so it cannot be a valid ${info.fileType} document. The file is corrupt, incomplete, or mislabeled. If you are sure it is fine, please create a ticket in Issues on github with the file to reproduce the error.`,
     [types_js_1.OfficeErrorType.MAX_NESTING_DEPTH_EXCEEDED]: `Document nesting depth exceeded the safe limit (possible denial-of-service input)`,
     [types_js_1.OfficeErrorType.EMBEDDING_TIMEOUT]: (timeout) => `Embedding call timed out after ${timeout}ms`
 };
@@ -60,6 +68,8 @@ const WARNING_MESSAGES = {
     [types_js_1.OfficeWarningType.TABLE_CELL_LIMIT_EXCEEDED]: (limit) => `Table cell limit (${limit}) reached while expanding repeated ODF cells/rows; the remaining cells were not materialized. A few hundred bytes of XML can request an unbounded number of cells via table:number-columns-repeated / table:number-rows-repeated, so this is capped. Raise decompressionLimits.maxTableCells if your documents legitimately exceed it.`,
     [types_js_1.OfficeWarningType.INVALID_CONTAINER_WIDTH]: (val) => `Invalid HTML containerWidth: ${JSON.stringify(val)}. Falling back to "auto". Width must be a positive number, a valid CSS length string (e.g., "900px", "100%", "50vw"), or "auto".`,
     [types_js_1.OfficeWarningType.METADATA_NOT_REPRESENTABLE]: (info) => `Custom metadata ${info.keys.map(k => `'${k}'`).join(', ')} could not be written to ${info.format} output: the format has a fixed metadata vocabulary with no place for caller-defined keys. The named metadata fields (title, author, etc.) were still applied.`,
+    [types_js_1.OfficeWarningType.NO_WORKSHEETS_FOUND]: `Workbook contains no worksheet parts (xl/worksheets/). If the workbook holds only chartsheets this is expected and there is simply no cell text to extract; otherwise the file may be incomplete.`,
+    [types_js_1.OfficeWarningType.NO_SLIDES_FOUND]: `Presentation contains no slides (ppt/slides/). A legitimately empty presentation produces this too, but if you expected content the file may be incomplete.`,
     [types_js_1.OfficeWarningType.INVALID_STYLE_MAP_TAG]: (tag) => `styleMap output.tag ${JSON.stringify(tag)} is not an allowed element name and was ignored; the node's default tag was used instead. A tag name is written into both the opening and closing tag, so only a known-safe set of block, heading and inline elements is accepted.`
 };
 /**
@@ -122,13 +132,23 @@ const getOfficeError = (type, config, info) => {
         details: info
     };
     reportIssue(issue, config);
-    return new Error(ERRORHEADER + message);
+    const error = new Error(ERRORHEADER + message);
+    // Brand the error with the issue that produced it so getWrappedError can tell an
+    // already-reported, already-prefixed OfficeParser error from a raw third-party one.
+    error.officeIssue = issue;
+    return error;
 };
 exports.getOfficeError = getOfficeError;
 /**
  * Wraps an existing error with OfficeParser context and performs corruption detection.
  * Optionally logs the error to console.
  *
+ * An error already built by {@link getOfficeError} is returned untouched: it carries an
+ * `officeIssue`, meaning it has been reported once and already bears the `[OfficeParser]: `
+ * header. Re-wrapping it would report the same issue a second time, prepend a second header,
+ * and flatten its specific error code to `FILE_CORRUPTED`. This is a marker check on the error
+ * object rather than a test against its message text, so it stays independent of wording.
+ *
  * **Important**: Do NOT pass AbortErrors to this function. AbortErrors (err.name === 'AbortError')
  * represent deliberate user cancellation and must be re-thrown as-is from the catch block so that
  * callers can reliably detect them via `err.name === 'AbortError'` or `err instanceof DOMException`.
@@ -140,6 +160,8 @@ exports.getOfficeError = getOfficeError;
  * @returns The wrapped Error object to be thrown
  */
 const getWrappedError = (error, config, filePath) => {
+    if (error?.officeIssue)
+        return error;
     let message = error.message || error;
     let code = types_js_1.OfficeErrorType.FILE_CORRUPTED; // Default for wrapped errors
     // Detect file corruption from common library error messages

package/dist/utils/zipUtils.d.ts

@@ -13,12 +13,12 @@
  *
  * @module zipUtils
  */
-import { DecompressionLimits } from '../types.js';
+import { DecompressionLimits, OfficeParserConfig, SupportedFileType } from '../types.js';
 /**
  * Represents a file extracted from a ZIP archive.
  * Contains the file's path within the archive and its content as a Buffer.
  */
-interface ZipFileContent {
+export interface ZipFileContent {
     /**
      * The relative path of the file within the ZIP archive.
      * @example "word/document.xml", "xl/worksheets/sheet1.xml", "ppt/slides/slide1.xml"
@@ -46,6 +46,9 @@ interface ZipFileContent {
  * @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.
+ * @param limits - Decompression limits guarding against zip bombs
+ * @param config - Parser configuration, so extraction failures honour `onWarning` /
+ *                 `outputErrorToConsole` like every other reported issue
  * @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
  *
@@ -70,5 +73,62 @@ interface ZipFileContent {
  *
  * @see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT ZIP file format specification
  */
-export declare const extractFiles: (zipInput: Buffer, filterFn: (fileName: string) => boolean, limits: DecompressionLimits) => Promise<ZipFileContent[]>;
-export {};
+export declare const extractFiles: (zipInput: Buffer, filterFn: (fileName: string) => boolean, limits: DecompressionLimits, config?: OfficeParserConfig) => Promise<ZipFileContent[]>;
+/**
+ * Finds the archive part that every document of a given format must contain, and fails loudly
+ * when it is absent.
+ *
+ * A readable ZIP archive is not by itself a document: an archive can decompress perfectly and
+ * still be a renamed photo bundle, a partial upload, or a file mislabeled with the wrong
+ * extension. Without this check a parser finds no content to walk and returns an empty AST,
+ * which a caller cannot distinguish from a document that genuinely has nothing in it. Every
+ * ZIP-backed format has one part it cannot be valid without, so its absence is a hard error.
+ *
+ * Pass the parser's own regex/predicate for the part rather than a fresh copy of the path, so
+ * this check and the code that later reads the part cannot drift apart.
+ *
+ * @param files - The entries extracted from the archive
+ * @param matcher - Predicate identifying the required part by its path within the archive
+ * @param config - Parser configuration, so the error is reported through the caller's handlers
+ * @param info - The document format and the human-readable part name, used in the message
+ * @returns The matching entry
+ * @throws {Error} A typed REQUIRED_PART_MISSING error when no entry matches
+ *
+ * @example
+ * ```typescript
+ * const document = findRequiredPart(files, p => !!p.match(documentFileRegex), config,
+ *     { fileType: 'docx', part: 'word/document.xml' });
+ * ```
+ */
+export declare const findRequiredPart: (files: ZipFileContent[], matcher: (path: string) => boolean, config: OfficeParserConfig, info: {
+    fileType: string;
+    part: string;
+}) => ZipFileContent;
+/**
+ * Resolves which office format a ZIP archive actually holds, by reading the part that names it.
+ *
+ * This exists because magic-byte sniffing is a heuristic that gives up. `file-type` identifies an
+ * OOXML package by parsing `[Content_Types].xml`, but it walks the archive under fixed budgets:
+ * at most 1024 entries, and (for entries whose sizes are deferred to a trailing data descriptor,
+ * general-purpose flag bit 3) about 1 MiB of scanning to locate those descriptors. An archive
+ * that puts enough data before `[Content_Types].xml` to exhaust either budget is reported as a
+ * generic `zip`, which previously surfaced to the caller as "add support for zip files" for a
+ * perfectly valid document. Both layouts occur in the wild: streaming ZIP writers set bit 3, and
+ * a media-heavy deck can hold more than 1024 parts.
+ *
+ * We already ship a ZIP reader that has neither limitation, so rather than guessing from the
+ * first bytes this opens the archive and reads the declaration directly. It is deliberately the
+ * fallback rather than the primary check, since the byte-level sniff is far cheaper and settles
+ * every non-ZIP format.
+ *
+ * @param zipInput - The candidate archive
+ * @param limits - Decompression limits, so sniffing an untrusted file stays bounded
+ * @returns The format the archive declares, or `undefined` if it declares none or cannot be read
+ *
+ * @example
+ * ```typescript
+ * // A presentation whose [Content_Types].xml sits behind 2 MiB of streamed entries
+ * await detectOfficeTypeFromZip(buffer, limits); // -> 'pptx'
+ * ```
+ */
+export declare const detectOfficeTypeFromZip: (zipInput: Buffer, limits: DecompressionLimits) => Promise<SupportedFileType | undefined>;

package/dist/utils/zipUtils.js

@@ -15,10 +15,26 @@
  * @module zipUtils
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractFiles = void 0;
+exports.detectOfficeTypeFromZip = exports.findRequiredPart = exports.extractFiles = void 0;
 const fflate_1 = require("fflate");
 const types_js_1 = require("../types.js");
 const errorUtils_js_1 = require("./errorUtils.js");
+/**
+ * Signature of the End Of Central Directory record ("PK\x05\x06"), the trailer every ZIP
+ * archive ends with. Its presence is what distinguishes a complete archive from one that
+ * was cut off in transfer.
+ */
+const EOCD_SIGNATURE = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+/** Size of the fixed portion of an End Of Central Directory record, in bytes. */
+const EOCD_RECORD_MIN_BYTES = 22;
+/** Maximum size of the optional archive comment that may trail the EOCD record, in bytes. */
+const ZIP_MAX_COMMENT_BYTES = 65535;
+/**
+ * How far back from the end of the input the EOCD record may start. The record is last in
+ * the file apart from its own variable-length comment, so searching this window is
+ * sufficient and bounded regardless of archive size.
+ */
+const EOCD_SEARCH_WINDOW_BYTES = EOCD_RECORD_MIN_BYTES + ZIP_MAX_COMMENT_BYTES;
 /**
  * Extracts files from a ZIP archive with optional filtering.
  *
@@ -34,6 +50,9 @@ const errorUtils_js_1 = require("./errorUtils.js");
  * @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.
+ * @param limits - Decompression limits guarding against zip bombs
+ * @param config - Parser configuration, so extraction failures honour `onWarning` /
+ *                 `outputErrorToConsole` like every other reported issue
  * @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
  *
@@ -58,7 +77,7 @@ const errorUtils_js_1 = require("./errorUtils.js");
  *
  * @see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT ZIP file format specification
  */
-const extractFiles = (zipInput, filterFn, limits) => {
+const extractFiles = (zipInput, filterFn, limits, config) => {
     const maxUncompressedBytes = limits?.maxUncompressedBytes !== undefined && Number.isFinite(limits.maxUncompressedBytes) && limits.maxUncompressedBytes >= 0
         ? limits.maxUncompressedBytes
         : 512 * 1024 * 1024;
@@ -93,7 +112,7 @@ const extractFiles = (zipInput, filterFn, limits) => {
                 return;
             totalEntryCount++;
             if (totalEntryCount > maxZipEntries) {
-                fail((0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.ZIP_ENTRY_COUNT_LIMIT_EXCEEDED, undefined, maxZipEntries));
+                fail((0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.ZIP_ENTRY_COUNT_LIMIT_EXCEEDED, config, maxZipEntries));
                 return;
             }
             if (!filterFn(file.name))
@@ -111,7 +130,7 @@ const extractFiles = (zipInput, filterFn, limits) => {
                 if (chunk && chunk.length) {
                     actualTotalBytes += chunk.length;
                     if (actualTotalBytes > maxUncompressedBytes) {
-                        fail((0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.ZIP_SIZE_LIMIT_EXCEEDED, undefined, maxUncompressedBytes));
+                        fail((0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.ZIP_SIZE_LIMIT_EXCEEDED, config, maxUncompressedBytes));
                         return;
                     }
                     chunks.push(Buffer.from(chunk));
@@ -147,7 +166,172 @@ const extractFiles = (zipInput, filterFn, limits) => {
             return;
         }
         pushComplete = true;
+        // fflate's streaming Unzip emits nothing, and no error, when the input is not a
+        // ZIP archive, unlike the central-directory-based unzip() this replaced (which
+        // rejected with "invalid zip data"). Zero entries can never be a valid document
+        // here, since every ZIP-backed format requires at least one part, so treat it as
+        // corrupt input rather than resolving into an empty, successfully-parsed document.
+        //
+        // This is checked before the truncation check below because it produces the better
+        // message for input that is not an archive at all, and because garbage that happens
+        // to contain the EOCD signature would otherwise slip past.
+        if (totalEntryCount === 0) {
+            fail((0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.ZIP_NO_ENTRIES_FOUND, config));
+            return;
+        }
+        // The streaming reader recovers entries from local file headers alone, so an archive
+        // cut short still yields whatever entries preceded the cut - silently, and possibly
+        // missing parts that came after it. The central-directory-based reader used before
+        // 7.3.0 rejected such input outright. Requiring the trailer that terminates every
+        // complete archive restores that: absent it, the data is truncated and the entries
+        // recovered cannot be trusted to be the whole document.
+        //
+        // Deliberately not gated on pendingFiles: when a cut lands inside an entry's
+        // compressed data that entry's final callback never fires, so this is also what
+        // settles the promise instead of leaving the caller waiting forever.
+        const tail = zipInput.subarray(Math.max(0, zipInput.length - EOCD_SEARCH_WINDOW_BYTES));
+        const eocdIndex = tail.lastIndexOf(EOCD_SIGNATURE);
+        if (eocdIndex === -1 || eocdIndex + EOCD_RECORD_MIN_BYTES > tail.length) {
+            fail((0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.ZIP_TRUNCATED, config));
+            return;
+        }
         maybeResolve();
     });
 };
 exports.extractFiles = extractFiles;
+/**
+ * Finds the archive part that every document of a given format must contain, and fails loudly
+ * when it is absent.
+ *
+ * A readable ZIP archive is not by itself a document: an archive can decompress perfectly and
+ * still be a renamed photo bundle, a partial upload, or a file mislabeled with the wrong
+ * extension. Without this check a parser finds no content to walk and returns an empty AST,
+ * which a caller cannot distinguish from a document that genuinely has nothing in it. Every
+ * ZIP-backed format has one part it cannot be valid without, so its absence is a hard error.
+ *
+ * Pass the parser's own regex/predicate for the part rather than a fresh copy of the path, so
+ * this check and the code that later reads the part cannot drift apart.
+ *
+ * @param files - The entries extracted from the archive
+ * @param matcher - Predicate identifying the required part by its path within the archive
+ * @param config - Parser configuration, so the error is reported through the caller's handlers
+ * @param info - The document format and the human-readable part name, used in the message
+ * @returns The matching entry
+ * @throws {Error} A typed REQUIRED_PART_MISSING error when no entry matches
+ *
+ * @example
+ * ```typescript
+ * const document = findRequiredPart(files, p => !!p.match(documentFileRegex), config,
+ *     { fileType: 'docx', part: 'word/document.xml' });
+ * ```
+ */
+const findRequiredPart = (files, matcher, config, info) => {
+    const found = files.find(file => matcher(file.path));
+    if (!found)
+        throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.REQUIRED_PART_MISSING, config, info);
+    return found;
+};
+exports.findRequiredPart = findRequiredPart;
+/** The part naming an OOXML package's document type. */
+const OOXML_CONTENT_TYPES_PATH = '[Content_Types].xml';
+/** The part naming an ODF or EPUB package's document type. */
+const ODF_MIMETYPE_PATH = 'mimetype';
+/**
+ * Substrings of the main-part content type each OOXML format declares in
+ * `[Content_Types].xml`, matched as plain text because only this one value is needed.
+ */
+const OOXML_MAIN_CONTENT_TYPES = [
+    ['wordprocessingml.document.main+xml', 'docx'],
+    ['spreadsheetml.sheet.main+xml', 'xlsx'],
+    ['presentationml.presentation.main+xml', 'pptx'],
+];
+/** Exact `mimetype` entry contents for the packages that carry one. */
+const PACKAGE_MIMETYPES = {
+    'application/vnd.oasis.opendocument.text': 'odt',
+    'application/vnd.oasis.opendocument.spreadsheet': 'ods',
+    'application/vnd.oasis.opendocument.presentation': 'odp',
+    'application/epub+zip': 'epub',
+};
+/** First two bytes of every ZIP local file header ("PK"). */
+const ZIP_MAGIC_BYTES = [0x50, 0x4b];
+/**
+ * Reporting is suppressed while sniffing: the input is not yet known to be a document, so a
+ * failure here is an inconclusive guess rather than something the caller did wrong. Without a
+ * config, `getOfficeError` would write these to the console.
+ */
+const SILENT_DETECTION_CONFIG = { outputErrorToConsole: false };
+/** Whether a buffer starts with the ZIP local file header signature. */
+const looksLikeZip = (buffer) => buffer.length >= ZIP_MAGIC_BYTES.length && ZIP_MAGIC_BYTES.every((byte, i) => buffer[i] === byte);
+/**
+ * How much a type sniff may inflate before giving up, in bytes.
+ *
+ * The two parts read here name the format and nothing else, so they are tiny in any real
+ * document: a few hundred bytes of `mimetype`, a few kilobytes of `[Content_Types].xml`. A
+ * crafted archive could declare them as hundreds of megabytes, and since the document is
+ * inflated again during the parse that follows, honouring the full decompression budget here
+ * would let a single call spend it twice. This cap keeps sniffing cheap; an archive that
+ * exceeds it is simply reported as unidentified.
+ */
+const MAX_DETECTION_INFLATED_BYTES = 4 * 1024 * 1024;
+/**
+ * Resolves which office format a ZIP archive actually holds, by reading the part that names it.
+ *
+ * This exists because magic-byte sniffing is a heuristic that gives up. `file-type` identifies an
+ * OOXML package by parsing `[Content_Types].xml`, but it walks the archive under fixed budgets:
+ * at most 1024 entries, and (for entries whose sizes are deferred to a trailing data descriptor,
+ * general-purpose flag bit 3) about 1 MiB of scanning to locate those descriptors. An archive
+ * that puts enough data before `[Content_Types].xml` to exhaust either budget is reported as a
+ * generic `zip`, which previously surfaced to the caller as "add support for zip files" for a
+ * perfectly valid document. Both layouts occur in the wild: streaming ZIP writers set bit 3, and
+ * a media-heavy deck can hold more than 1024 parts.
+ *
+ * We already ship a ZIP reader that has neither limitation, so rather than guessing from the
+ * first bytes this opens the archive and reads the declaration directly. It is deliberately the
+ * fallback rather than the primary check, since the byte-level sniff is far cheaper and settles
+ * every non-ZIP format.
+ *
+ * @param zipInput - The candidate archive
+ * @param limits - Decompression limits, so sniffing an untrusted file stays bounded
+ * @returns The format the archive declares, or `undefined` if it declares none or cannot be read
+ *
+ * @example
+ * ```typescript
+ * // A presentation whose [Content_Types].xml sits behind 2 MiB of streamed entries
+ * await detectOfficeTypeFromZip(buffer, limits); // -> 'pptx'
+ * ```
+ */
+const detectOfficeTypeFromZip = async (zipInput, limits) => {
+    if (!looksLikeZip(zipInput))
+        return undefined;
+    let files;
+    try {
+        files = await (0, exports.extractFiles)(zipInput, name => name === OOXML_CONTENT_TYPES_PATH || name === ODF_MIMETYPE_PATH, 
+        // Never inflate more for a sniff than the caller already allows for the parse, and
+        // never more than a sniff could legitimately need.
+        {
+            ...limits,
+            maxUncompressedBytes: Math.min(limits?.maxUncompressedBytes ?? MAX_DETECTION_INFLATED_BYTES, MAX_DETECTION_INFLATED_BYTES),
+        }, SILENT_DETECTION_CONFIG);
+    }
+    catch {
+        // Unreadable, truncated, or not an archive at all. The caller keeps whatever the
+        // byte-level sniff decided, and the parser it dispatches to reports the real problem.
+        return undefined;
+    }
+    // ODF and EPUB state their type outright, so prefer that over inspecting OOXML parts.
+    const mimetypeEntry = files.find(file => file.path === ODF_MIMETYPE_PATH);
+    if (mimetypeEntry) {
+        const declared = PACKAGE_MIMETYPES[mimetypeEntry.content.toString().trim()];
+        if (declared)
+            return declared;
+    }
+    const contentTypesEntry = files.find(file => file.path === OOXML_CONTENT_TYPES_PATH);
+    if (contentTypesEntry) {
+        const contentTypes = contentTypesEntry.content.toString();
+        const match = OOXML_MAIN_CONTENT_TYPES.find(([marker]) => contentTypes.includes(marker));
+        if (match)
+            return match[1];
+    }
+    return undefined;
+};
+exports.detectOfficeTypeFromZip = detectOfficeTypeFromZip;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "officeparser",
-  "version": "7.5.0",
+  "version": "7.5.1",
   "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, .epub) and generating high-fidelity outputs in Markdown, HTML, CSV, RTF, PDF, EPUB, and RAG-focused chunks.",
   "funding": "https://github.com/sponsors/harshankur",
   "main": "dist/index.js",