officeparser 7.4.0 → 7.5.1

package/README.md

@@ -128,7 +128,7 @@ npx officeparser my_document --fileType=docx --to=json
 | `--includeRawContent` | boolean | `false` | Include raw XML/RTF in nodes |
 | `--serializeRawContent` | boolean | `true` | Include stringified XML in metadata |
 | `--preserveXmlWhitespace` | boolean | `false` | Keep raw formatting space |
-| `--includeBreakNodes` | boolean | `false` | Include break nodes (DOCX only) |
+| `--includeBreakNodes` | boolean | `false` | Include break nodes (DOCX and ODF) |
 | `--verbose` | boolean | `false` | Show full error stack traces and warning logs |
 | `--includeFormatting` | boolean | `true` | Include formatting style map matching |
 | `--renderMetadata` | boolean | `false` | Render metadata as visible content in the generated output |
@@ -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
@@ -608,7 +645,14 @@ formatting: {
 }
 ```
 
-### 6. Break Nodes (DOCX only)
+> [!NOTE]
+> On a **content node**, an absent flag and `false` mean the same thing — the flag is simply not
+> applied. On **`ast.metadata.styleMap`**, they differ: an absent flag means the style says nothing
+> about that property (so it inherits), while `false` means the style explicitly turns it off
+> (ODF's `fo:font-weight="normal"`, DOCX's `<w:b w:val="0"/>`). Code resolving inheritance itself
+> must test `=== undefined`, not truthiness, or it will treat "explicitly off" as "unspecified".
+
+### 6. Break Nodes (DOCX and ODF)
 
 When `includeBreakNodes: true`, break elements appear as nodes:
 
@@ -623,6 +667,43 @@ Break Node (type: 'break')
 > [!NOTE]
 > Break nodes have no `text` property, but `ast.toText()` and `ast.to('text')` automatically convert them to the configured newline delimiter.
 
+> [!NOTE]
+> DOCX writes breaks inline (`w:br`/`w:cr`), so they land as children of the paragraph. ODF instead
+> carries page and column breaks on the paragraph *style* (`fo:break-before`/`fo:break-after`), so those
+> are emitted as siblings around the paragraph rather than inside it. `<text:soft-page-break/>` maps onto
+> `lastRenderedPage`, the same type as DOCX's `w:lastRenderedPageBreak`.
+
+### 6b. Equations
+
+Equations are extracted from every format that can carry them and normalized to **LaTeX**, so a
+formula means the same thing whichever format it arrived in:
+
+| Source format | Markup in the file |
+|---|---|
+| DOCX, PPTX | OOXML `<m:oMath>` / `<m:oMathPara>` |
+| ODT, ODP, ODS | MathML inside the embedded formula object |
+| HTML, EPUB | native MathML `<math>` |
+| Markdown | `$inline$` / `$$block$$` |
+
+They all land as the same node:
+
+```text
+Code Node (type: 'code')
+├── text: '\\frac{1}{2}'          // LaTeX, whatever the source markup was
+└── metadata: { math: 'inline' | 'block' }
+```
+
+Fractions, sub/superscripts, radicals, delimiters, n-ary operators (sums, integrals), named
+functions, accents, bars, matrices and math alphabets (`ℝ`, `𝒜`, …) are all preserved. When a
+document supplies its own TeX source in an `<annotation encoding="application/x-tex">`, that is
+used verbatim in preference to anything reconstructed from the presentation markup.
+
+> [!NOTE]
+> Equation text is *structure*, not prose: a fraction whose numerator and denominator are simply
+> concatenated reads as a different number rather than as obviously-missing content. Consumers that
+> index document text should treat `code` nodes carrying `math` as opaque LaTeX rather than
+> splitting them as words.
+
 ### 7. Document Metadata
 
 ```ts
@@ -688,7 +769,7 @@ idempotent and `.md → AST → HTML → AST → .md` survives unchanged.
 | Attribute lists | `![alt](img.png){width=50% .centered}` | `ImageMetadata.width` / `.align`, `TableMetadata.align` |
 | Citations | `[@smith2024]` | `TextMetadata.citationKey` |
 | Wikilinks | `[[Page]]` / `[[Page\|Alias]]` | `TextMetadata.wikilink`, `.link`, `.linkType` |
-| Inline/block math | `$E=mc^2$` / `` $$...$$ `` | `TextMetadata.math` (`'inline' \| 'block'`) |
+| Inline/block math | `$E=mc^2$` / `` $$...$$ `` | `type: 'code'`, `CodeMetadata.math` (`'inline' \| 'block'`) |
 | Frontmatter arrays | `tags: [a, b]` or `tags: ["a","b"]` | Real array in `metadata.customProperties`/`nativeProperties` |
 | MDX components (import-only) | `<Component prop="x">...</Component>` | Stripped; inner Markdown is kept. Never generated back. |
 
@@ -888,7 +969,7 @@ Pass as the second argument to `parseOffice(file, config)`.
 | `includeRawContent` | `boolean` | `false` | Attach raw XML/RTF source to each node |
 | `serializeRawContent` | `boolean` | `true` | Re-serialize XML to clean strings (only if `includeRawContent: true`) |
 | `preserveXmlWhitespace` | `boolean` | `false` | Preserve original XML whitespace during serialization |
-| `includeBreakNodes` | `boolean` | `false` | Include `w:br` / `w:cr` as typed break nodes (DOCX only) |
+| `includeBreakNodes` | `boolean` | `false` | Include typed break nodes: DOCX `w:br`/`w:cr`, ODF `fo:break-before`/`fo:break-after` and `text:soft-page-break` |
 | `ignoreInternalLinks` | `boolean` | `false` | Strip bookmarks and internal cross-references from AST |
 | `fileType` | `SupportedFileType \| null` | `null` | **Required for text-based binary data** (`'md'`, `'html'`, `'csv'`) as these lack magic bytes. |
 | `csvDelimiter` | `string` | `','` | Input delimiter when parsing CSV files |

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/generators/BaseGenerator.d.ts

@@ -81,6 +81,21 @@ export declare abstract class BaseGenerator<D extends UniversalGeneratorFormat =
      * hasn't already been claimed; otherwise a sequential counter guarantees uniqueness.
      */
     protected getFootnoteKey(note: OfficeContentNode): string;
+    /**
+     * True when every content-bearing text descendant satisfies `test` - i.e. the property is
+     * uniform across the whole node and therefore says nothing the node type does not already say.
+     *
+     * Used to decide whether a heading's or header row's inherited formatting can be dropped. The
+     * distinction matters: an ODF heading whose paragraph style is bold and 14pt yields a heading
+     * where *every* run is bold and 14pt, and re-emitting that gives `# **Heading**` in Markdown
+     * and, worse in RTF/HTML, an inner font-size that overrides the heading's own and visibly
+     * shrinks it. But `# Normal **Bold** Normal` is an author contrasting one word against the
+     * rest, and dropping that would discard real meaning. Only the uniform case is safe.
+     *
+     * Returns false when there is no text to judge, so an empty or image-only node never triggers
+     * suppression.
+     */
+    protected hasUniformFormatting(node: OfficeContentNode, test: (formatting: OfficeContentNode['formatting']) => boolean): boolean;
     /**
      * Recursively extracts plain text from a node and its children.
      */

package/dist/generators/BaseGenerator.js

@@ -187,6 +187,37 @@ class BaseGenerator {
         this.noteFootnoteKeys.set(note, key);
         return key;
     }
+    /**
+     * True when every content-bearing text descendant satisfies `test` - i.e. the property is
+     * uniform across the whole node and therefore says nothing the node type does not already say.
+     *
+     * Used to decide whether a heading's or header row's inherited formatting can be dropped. The
+     * distinction matters: an ODF heading whose paragraph style is bold and 14pt yields a heading
+     * where *every* run is bold and 14pt, and re-emitting that gives `# **Heading**` in Markdown
+     * and, worse in RTF/HTML, an inner font-size that overrides the heading's own and visibly
+     * shrinks it. But `# Normal **Bold** Normal` is an author contrasting one word against the
+     * rest, and dropping that would discard real meaning. Only the uniform case is safe.
+     *
+     * Returns false when there is no text to judge, so an empty or image-only node never triggers
+     * suppression.
+     */
+    hasUniformFormatting(node, test) {
+        let sawText = false;
+        const walk = (n) => {
+            if (n.type === 'text') {
+                // Whitespace-only runs carry no visible formatting either way, so they neither
+                // count as evidence nor veto - otherwise a stray unformatted space between two
+                // bold runs would defeat the check on almost every real heading.
+                if (!(n.text || '').trim())
+                    return true;
+                sawText = true;
+                return test(n.formatting);
+            }
+            return (n.children ?? []).every(walk);
+        };
+        const uniform = (node.children ?? []).every(walk);
+        return sawText && uniform;
+    }
     /**
      * Recursively extracts plain text from a node and its children.
      */

package/dist/generators/HtmlGenerator.d.ts

@@ -6,6 +6,14 @@ import { BaseGenerator } from './BaseGenerator.js';
 export declare class HtmlGenerator extends BaseGenerator<'html'> {
     private chartCounter;
     private isSpreadsheetMode;
+    /**
+     * Set while rendering a heading's children, so `formatText` can drop the run-level bold and
+     * font-size the `<hN>` already establishes. See the note there, and the identical flag in
+     * `RtfGenerator`, where the same inherited size actively shrinks the heading.
+     */
+    private inHeading;
+    /** As `inHeading`, but for the inherited font size - see `hasUniformFormatting`. */
+    private headingUniformSize;
     constructor(ast: OfficeParserAST, config?: GeneratorConfig<'html'>);
     /**
      * Generates HTML string from the provided AST.
@@ -24,6 +32,7 @@ export declare class HtmlGenerator extends BaseGenerator<'html'> {
      */
     private tableNestingLevel;
     protected processNodeRecursive(node: OfficeContentNode, processor: (node: OfficeContentNode, childrenOutput: string) => string | Promise<string>, override?: string | boolean | void): Promise<string>;
+    private processNodeRecursiveInner;
     /**
      * Internal processor for individual nodes.
      */

package/dist/generators/HtmlGenerator.js

@@ -88,6 +88,14 @@ function resolveStandalone(standalone) {
 class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
     chartCounter = 0;
     isSpreadsheetMode = false;
+    /**
+     * Set while rendering a heading's children, so `formatText` can drop the run-level bold and
+     * font-size the `<hN>` already establishes. See the note there, and the identical flag in
+     * `RtfGenerator`, where the same inherited size actively shrinks the heading.
+     */
+    inHeading = false;
+    /** As `inHeading`, but for the inherited font size - see `hasUniformFormatting`. */
+    headingUniformSize = false;
     constructor(ast, config) {
         super('html', ast, config);
     }
@@ -502,6 +510,21 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
         // method entirely, so without repeating the check here the signal would be silently
         // inert for this generator - which is exactly how it was missed.
         (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
+        const wasInHeading = this.inHeading;
+        const wasHeadingSize = this.headingUniformSize;
+        if (node.type === 'heading') {
+            this.inHeading = this.hasUniformFormatting(node, f => f?.bold === true);
+            this.headingUniformSize = this.hasUniformFormatting(node, f => !!f?.size);
+        }
+        try {
+            return await this.processNodeRecursiveInner(node, processor, override);
+        }
+        finally {
+            this.inHeading = wasInHeading;
+            this.headingUniformSize = wasHeadingSize;
+        }
+    }
+    async processNodeRecursiveInner(node, processor, override) {
         // Use pre-evaluated override if provided, otherwise call handleOnNode
         const actualOverride = override !== undefined ? override : await this.handleOnNode(node);
         // Returning false skips the node and its children
@@ -1076,7 +1099,12 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
         let result = this.escape(text);
         const f = node.formatting;
         if (this.config.includeFormatting && f) {
-            if (f.bold)
+            // Inside an `<hN>`, the heading's own styling is authoritative. A run that also carries
+            // bold and a font size - the normal case for ODF, where a heading's paragraph style is
+            // inherited by its runs - would wrap the text in `<b>` the heading already implies and,
+            // worse, in a `<span style="font-size: 14pt">` that *shrinks* the heading to the size
+            // its paragraph style happened to name. See the same suppression in RtfGenerator.
+            if (f.bold && !this.inHeading)
                 result = `<b>${result}</b>`;
             if (f.italic)
                 result = `<i>${result}</i>`;
@@ -1088,7 +1116,9 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 result = `<sub>${result}</sub>`;
             if (f.superscript)
                 result = `<sup>${result}</sup>`;
-            const styles = this.getInlineStyles(node);
+            const styles = this.headingUniformSize
+                ? this.getInlineStyles(node, { skipFontSize: true })
+                : this.getInlineStyles(node);
             if (styles) {
                 result = `<span style="${styles}">${result}</span>`;
             }
@@ -1120,7 +1150,7 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
         }
         return result;
     }
-    getInlineStyles(node) {
+    getInlineStyles(node, options = {}) {
         const styles = [];
         // Colors/sizes/fonts/alignments are free strings from an untrusted document;
         // run each through sanitizeCssValue so it can't break out of the style="" attribute
@@ -1154,7 +1184,7 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 pushSafe('color', f.color);
             if (f.backgroundColor)
                 pushSafe('background-color', f.backgroundColor);
-            if (f.size)
+            if (f.size && !options.skipFontSize)
                 pushSafe('font-size', f.size);
             if (f.font) {
                 const safeFont = (0, sanitize_js_1.sanitizeCssValue)(f.font);

package/dist/generators/MarkdownGenerator.d.ts

@@ -31,6 +31,18 @@ import { BaseGenerator } from './BaseGenerator.js';
  */
 export declare class MarkdownGenerator extends BaseGenerator<'md'> {
     private isInsideTable;
+    /**
+     * Set while rendering the children of a heading, or the cells of a table's header row.
+     *
+     * Markdown already conveys "this is a heading" with `#` and "this is a header row" with the
+     * separator line, so a run inside one that also carries bold - the normal case for ODF, whose
+     * heading and header-row paragraph styles are bold and are now inherited by their runs - would
+     * render as `# **Heading**` and `| **ITEM** |`. That is redundant rather than wrong, but it
+     * also round-trips back into bold text nodes nested inside a heading, so the noise compounds
+     * on every parse/generate cycle. Emphasis the node type already implies is dropped; every
+     * other formatting flag still comes through.
+     */
+    private inImplicitBold;
     private hoistedContent;
     private collectedAbbreviations;
     private resolvedDialect;
@@ -72,6 +84,7 @@ export declare class MarkdownGenerator extends BaseGenerator<'md'> {
     private optimizeNodes;
     private areFormattingEqual;
     private renderMarkdownTable;
+    private collectNotesFrom;
     private renderMarkdownTableInternal;
     private hasNestedTable;
     private hasColspanOrRowspan;