officeparser 7.1.0 → 7.2.1

package/dist/officeparser.browser.d.ts

@@ -7,6 +7,8 @@
 export declare enum OfficeErrorType {
 	/** Unsupported file extension */
 	EXTENSION_UNSUPPORTED = "EXTENSION_UNSUPPORTED",
+	/** Unsupported output generator format */
+	FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED",
 	/** File appears to be corrupted or malformed */
 	FILE_CORRUPTED = "FILE_CORRUPTED",
 	/** File could not be found at the specified path */
@@ -70,7 +72,9 @@ export declare enum OfficeWarningType {
 	/** No chunks were generated for the document given the current strategy */
 	EMPTY_CHUNK_GENERATED = "EMPTY_CHUNK_GENERATED",
 	/** A node was skipped because it only contained whitespace */
-	WHITESPACE_NODE_SKIPPED = "WHITESPACE_NODE_SKIPPED"
+	WHITESPACE_NODE_SKIPPED = "WHITESPACE_NODE_SKIPPED",
+	/** The HTML generator containerWidth option is invalid */
+	INVALID_CONTAINER_WIDTH = "INVALID_CONTAINER_WIDTH"
 }
 /**
  * Consolidated timeout settings for OCR operations.
@@ -223,10 +227,23 @@ export interface OfficeParserConfig {
 	 */
 	ignoreNotes?: boolean;
 	/**
-	 * Flag, if set to true, will collectively put all the parsed text from notes at last in files like powerpoint.
-	 * Default is false. It puts each notes right after its main slide content.
-	 * If ignoreNotes is set to true, this flag is also ignored.
-	 * @note This flag currently does not affect RTF files; RTF footnotes/endnotes are always collected and appended at the end of the content.
+	 * Flag to ignore comments from parsing.
+	 * Default is false.
+	 */
+	ignoreComments?: boolean;
+	/**
+	 * Flag to ignore headers and footers from parsing.
+	 * Default is false.
+	 */
+	ignoreHeadersAndFooters?: boolean;
+	/**
+	 * Flag to ignore slide masters from parsing in PowerPoint.
+	 * Default is false.
+	 */
+	ignoreSlideMasters?: boolean;
+	/**
+	 * @deprecated Notes are now structurally attached to the specific nodes they belong to via `node.notes`.
+	 * This option is now completely ignored by all parsers.
 	 */
 	putNotesAtLast?: boolean;
 	/**
@@ -351,9 +368,10 @@ export interface OfficeIssue {
 /**
  * The result of a document conversion operation.
  */
-export interface ConversionResult<D extends string = UniversalGeneratorFormat> {
+export type ConversionValue<D extends UniversalGeneratorFormat> = D extends "pdf" ? Uint8Array | string : D extends "chunks" ? OfficeChunk[] : D extends "csv" ? string | Uint8Array : string;
+export interface ConversionResult<D extends UniversalGeneratorFormat> {
 	/** The actual generated content (HTML, Markdown, Text, OfficeChunk[], etc.). */
-	value: D extends "pdf" ? Uint8Array : D extends "chunks" ? OfficeChunk[] : D extends "csv" ? string | Uint8Array : D extends UniversalGeneratorFormat ? string : never;
+	value: ConversionValue<D>;
 	/** A collection of issues (warnings/infos) generated during the process. */
 	messages: OfficeIssue[];
 }
@@ -381,7 +399,7 @@ export interface CommonGeneratorConfig {
 	 * 1. **Filter/Remove Nodes**: Return `false` to skip a node and all its children.
 	 * 2. **Override Rendering**: Return a `string` to use that exact text as the output, bypassing default logic and recursion.
 	 * 3. **Mutate Nodes**: Modify the `node` object directly (e.g., changing `node.text`) and return `void` to let the generator proceed with your changes.
-	 * 4. **Async Support**: The callback can be `async`, allowing you to fetch external data or perform complex logic during generation.
+	 * 4. **Async Support**: The callback can be `async`, allowing you to load external data or perform complex logic during generation.
 	 */
 	onNode?: (node: OfficeContentNode) => string | false | Promise<string | false | void> | void;
 	/**
@@ -475,17 +493,31 @@ export interface CommonGeneratorConfig {
  * Restricts format-specific configurations to their respective destinations.
  */
 /**
- * Mapping of destination formats to their specific configuration interfaces.
+ * Maps a destination format string to its corresponding specific configuration object type.
  */
-export interface GeneratorSubConfigMap {
-	html: HtmlGeneratorConfig;
-	md: MdGeneratorConfig;
-	pdf: PdfGeneratorConfig;
-	csv: CsvGeneratorConfig;
-	text: TextGeneratorConfig;
-	rtf: RtfGeneratorConfig;
-	chunks: ChunkingConfig;
-}
+export type GeneratorSpecificConfig<D extends string> = D extends "html" ? {
+	htmlConfig?: HtmlGeneratorConfig;
+} : D extends "md" ? {
+	mdConfig?: MdGeneratorConfig;
+} : D extends "pdf" ? {
+	pdfConfig?: PdfGeneratorConfig;
+} : D extends "csv" ? {
+	csvConfig?: CsvGeneratorConfig;
+} : D extends "text" ? {
+	textConfig?: TextGeneratorConfig;
+} : D extends "rtf" ? {
+	rtfConfig?: RtfGeneratorConfig;
+} : D extends "chunks" ? {
+	chunksConfig?: ChunkingConfig;
+} : Partial<{
+	htmlConfig: HtmlGeneratorConfig;
+	mdConfig: MdGeneratorConfig;
+	pdfConfig: PdfGeneratorConfig;
+	csvConfig: CsvGeneratorConfig;
+	textConfig: TextGeneratorConfig;
+	rtfConfig: RtfGeneratorConfig;
+	chunksConfig: ChunkingConfig;
+}>;
 /**
  * Configuration options for document generators.
  *
@@ -496,9 +528,7 @@ export interface GeneratorSubConfigMap {
  *
  * @template D The destination format string. Defaults to `string` for a general configuration.
  */
-export type GeneratorConfig<D extends string = string> = CommonGeneratorConfig & {
-	[K in keyof GeneratorSubConfigMap as `${K & string}Config`]?: string extends D ? GeneratorSubConfigMap[K] : (D extends K ? GeneratorSubConfigMap[K] : never);
-};
+export type GeneratorConfig<D extends string = string> = CommonGeneratorConfig & GeneratorSpecificConfig<D>;
 /**
  * Configuration options for the OfficeConverter.
  * Combines relevant parser and generator settings for a seamless one-step conversion.
@@ -530,6 +560,19 @@ export type OfficeConverterConfig<D extends string = string, T extends Supported
 	 */
 	onWarning?: (issue: OfficeIssue) => void;
 };
+/**
+ * Configuration options for granular raw HTML injections.
+ */
+export interface HtmlInjectionConfig {
+	/** Raw HTML injected immediately after the opening <head> tag */
+	headStart?: string;
+	/** Raw HTML injected immediately before the closing </head> tag */
+	headEnd?: string;
+	/** Raw HTML injected immediately after the opening <body> tag */
+	bodyStart?: string;
+	/** Raw HTML injected immediately before the closing </body> tag */
+	bodyEnd?: string;
+}
 /**
  * Configuration options for HTML generation.
  */
@@ -544,6 +587,25 @@ export interface HtmlGeneratorConfig {
 	 * Defaults to 'https://cdn.jsdelivr.net/npm/chart.js'.
 	 */
 	chartJsSrc?: string;
+	/**
+	 * Custom container width for the generated HTML.
+	 * Can be a number (pixels) or string (e.g., '900px', '100%').
+	 * If not specified or set to 'auto', it defaults based on the content type:
+	 * - Spreadsheet: '100%'
+	 * - Presentation/Slides: '1100px'
+	 * - Standard Document (PDF/DOCX/RTF/etc.): '900px'
+	 */
+	containerWidth?: string | number;
+	/**
+	 * Custom CSS to append to the generated HTML document.
+	 * This CSS will be included in the `<style>` block and can be used to style
+	 * custom classes added during AST manipulation or override default styles.
+	 */
+	customCss?: string;
+	/**
+	 * Granular injection points for custom HTML, scripts, and styles.
+	 */
+	injections?: HtmlInjectionConfig;
 }
 /**
  * Configuration options for PDF generation.
@@ -619,7 +681,7 @@ export interface StructuredStyleMapping {
 		 * The structural type of the node (e.g., 'paragraph', 'heading', 'text').
 		 * Most style mappings target 'paragraph' nodes to convert them into headers or blocks.
 		 */
-		nodeType?: string;
+		nodeType?: OfficeContentNodeType;
 		/**
 		 * A dictionary of attributes to match on the node.
 		 *
@@ -685,7 +747,7 @@ export interface CsvGeneratorConfig {
 	/**
 	 * Whether to merge all selected sheets into a single CSV.
 	 * If false, returns a ZIP archive containing individual CSV files.
-	 * Defaults to false.
+	 * Defaults to true.
 	 */
 	mergeSheets?: boolean;
 	/**
@@ -944,11 +1006,16 @@ export type SupportedFileType = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods"
 /**
  * Types of content nodes in the AST.
  */
-export type OfficeContentNodeType = "paragraph" | "heading" | "table" | "list" | "text" | "image" | "chart" | "drawing" | "slide" | "note" | "sheet" | "row" | "cell" | "page" | "break" | "code" | "comment";
+export type OfficeContentNodeType = "paragraph" | "heading" | "table" | "list" | "text" | "image" | "chart" | "drawing" | "slide" | "note" | "sheet" | "row" | "cell" | "page" | "break" | "code" | "comment" | "header" | "footer" | "slideMaster";
 /**
  * Supported MIME types for attachments.
  */
 export type OfficeMimeType = "image/jpeg" | "image/png" | "image/gif" | "image/bmp" | "image/tiff" | "image/svg+xml" | "application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.oasis.opendocument.chart" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.text" | "application/vnd.oasis.opendocument.presentation" | "application/rtf" | "text/csv" | "text/markdown" | "text/html";
+/**
+ * Text alignment options.
+ * Common in spreadsheet cells, paragraph styles, and text elements.
+ */
+export type TextAlignment = "left" | "center" | "right" | "justify";
 /**
  * Text formatting options available for text content.
  * Represents common formatting attributes found in office documents (DOCX, RTF, PPTX, etc.).
@@ -1022,7 +1089,7 @@ export interface TextFormatting {
 	 * Common in spreadsheet cells or paragraph styles.
 	 * @example "center", "right"
 	 */
-	alignment?: "left" | "center" | "right" | "justify";
+	alignment?: TextAlignment;
 }
 /**
  * Metadata for a slide in PowerPoint.
@@ -1072,7 +1139,7 @@ export interface HeadingMetadata {
 	/** The heading level (e.g., 1 for H1). */
 	level: number;
 	/** The alignment of the heading. */
-	alignment?: "left" | "center" | "right" | "justify";
+	alignment?: TextAlignment;
 	/** The style of the heading. */
 	style?: string;
 	/** Detailed indentation information. */
@@ -1085,7 +1152,7 @@ export interface HeadingMetadata {
  */
 export interface ParagraphMetadata {
 	/** The alignment of the paragraph. */
-	alignment?: "left" | "center" | "right" | "justify";
+	alignment?: TextAlignment;
 	/** The style of the paragraph. */
 	style?: string;
 	/** Detailed indentation information. */
@@ -1113,7 +1180,7 @@ export interface ListMetadata {
 	 * Text alignment of the list item.
 	 * @example 'left', 'center', 'right', 'justify'
 	 */
-	alignment: "left" | "center" | "right" | "justify";
+	alignment: TextAlignment;
 	/**
 	 * The list ID from the Word document's numbering definition.
 	 * Used to identify which list definition this item belongs to.
@@ -1163,6 +1230,15 @@ export interface CellMetadata {
 	style?: string;
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
+	/** Background color for this cell in hex format (e.g. #FFFFFF). */
+	backgroundColor?: string;
+}
+/**
+ * Metadata for a table.
+ */
+export interface TableMetadata {
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
 }
 /**
  * Metadata for a chart node in the document.
@@ -1250,6 +1326,8 @@ export interface NoteMetadata {
 	noteId?: string;
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
+	/** The slide number this note is associated with (used in PowerPoint). */
+	slideNumber?: number;
 }
 /**
  * Metadata for break nodes.
@@ -1285,10 +1363,25 @@ export interface CodeMetadata {
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
 }
+/**
+ * Metadata for a comment/annotation.
+ */
+export interface CommentMetadata {
+	author?: string;
+	initials?: string;
+	date?: string;
+	commentId?: string;
+}
+/**
+ * Metadata for a header or footer.
+ */
+export interface HeaderFooterMetadata {
+	type: "default" | "first" | "even" | string;
+}
 /**
  * Union type for content metadata.
  */
-export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | CodeMetadata | undefined;
+export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | CodeMetadata | CommentMetadata | HeaderFooterMetadata | TableMetadata | undefined;
 /**
  * Represents a node in the document content tree.
  * This is the core building block of the parsed document structure.
@@ -1315,13 +1408,10 @@ export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata |
  *   children: [...]
  * }
  */
-export interface OfficeContentNode {
-	/**
-	 * The type of the node.
-	 * Determines how the node should be interpreted and rendered.
-	 * Common types: 'paragraph', 'heading', 'table', 'list', 'text', 'image', etc.
-	 */
-	type: OfficeContentNodeType;
+/**
+ * Shared properties available on all document content nodes.
+ */
+export interface BaseContentNode {
 	/**
 	 * The complete text content of the node and all its children combined.
 	 * For container nodes (paragraph, heading), this is the concatenation of all child text.
@@ -1339,6 +1429,16 @@ export interface OfficeContentNode {
 	 * @example [{ type: 'text', text: 'Hello', formatting: { bold: true } }]
 	 */
 	children?: OfficeContentNode[];
+	/**
+	 * Comments attached to this specific node.
+	 * Keeps annotations completely separate from the actual content flow.
+	 */
+	comments?: OfficeContentNode[];
+	/**
+	 * Notes (like footnotes or slide notes) attached to this specific node.
+	 * Keeps notes separate from the actual structural children.
+	 */
+	notes?: OfficeContentNode[];
 	/**
 	 * Text formatting applied to this node.
 	 * Only applicable to text-containing nodes.
@@ -1346,16 +1446,6 @@ export interface OfficeContentNode {
 	 * @example { bold: true, size: "12", font: "Arial" }
 	 */
 	formatting?: TextFormatting;
-	/**
-	 * Type-specific metadata providing additional context about the node.
-	 * The metadata structure depends on the node type:
-	 * - Headings: { level: 1 }
-	 * - Lists: { listType: 'ordered', indentation: 0 }
-	 * - Cells: { row: 0, col: 0 }
-	 * - Slides: { slideNumber: 1 }
-	 * @example { level: 1 } for a heading
-	 */
-	metadata?: ContentMetadata;
 	/**
 	 * The raw source content for this node.
 	 * - For XML-based formats (DOCX, XLSX, PPTX): contains the raw XML
@@ -1367,6 +1457,93 @@ export interface OfficeContentNode {
 	 */
 	rawContent?: string;
 }
+/**
+ * Represents a node in the document content tree.
+ * This is the core building block of the parsed document structure.
+ * Content nodes can be nested to represent hierarchical document structures
+ * (e.g., paragraphs containing text runs, tables containing rows, rows containing cells).
+ *
+ * @example
+ * // A simple paragraph with formatted text
+ * {
+ *   type: 'paragraph',
+ *   text: 'Hello world',
+ *   children: [
+ *     { type: 'text', text: 'Hello ', formatting: { bold: true } },
+ *     { type: 'text', text: 'world', formatting: { italic: true } }
+ *   ]
+ * }
+ *
+ * @example
+ * // A heading with metadata
+ * {
+ *   type: 'heading',
+ *   text: 'Chapter 1',
+ *   metadata: { level: 1 },
+ *   children: [...]
+ * }
+ */
+export type OfficeContentNode = BaseContentNode & ({
+	type: "slide";
+	metadata?: SlideMetadata;
+} | {
+	type: "sheet";
+	metadata?: SheetMetadata;
+} | {
+	type: "heading";
+	metadata?: HeadingMetadata;
+} | {
+	type: "list";
+	metadata?: ListMetadata;
+} | {
+	type: "cell";
+	metadata?: CellMetadata;
+} | {
+	type: "image";
+	metadata?: ImageMetadata;
+} | {
+	type: "chart";
+	metadata?: ChartMetadata;
+} | {
+	type: "page";
+	metadata?: PageMetadata;
+} | {
+	type: "paragraph";
+	metadata?: ParagraphMetadata;
+} | {
+	type: "text";
+	metadata?: TextMetadata;
+} | {
+	type: "note";
+	metadata?: NoteMetadata;
+} | {
+	type: "break";
+	metadata?: BreakMetadata;
+} | {
+	type: "code";
+	metadata?: CodeMetadata;
+} | {
+	type: "comment";
+	metadata?: CommentMetadata;
+} | {
+	type: "header";
+	metadata?: HeaderFooterMetadata;
+} | {
+	type: "footer";
+	metadata?: HeaderFooterMetadata;
+} | {
+	type: "table";
+	metadata?: TableMetadata;
+} | {
+	type: "row";
+	metadata?: undefined;
+} | {
+	type: "drawing";
+	metadata?: undefined;
+} | {
+	type: "slideMaster";
+	metadata?: SlideMetadata;
+});
 /**
  * Structured information extracted from a chart.
  */
@@ -1506,14 +1683,40 @@ export interface OfficeMetadata {
 	 * Values are typed as string, number, boolean, or Date where the source format provides type information.
 	 */
 	customProperties?: Record<string, string | number | boolean | Date>;
+	/** Keywords associated with the document. */
+	keywords?: string;
+	/**
+	 * Contains all format-specific metadata fields extracted verbatim.
+	 * Consumers can use this to access properties not mapped to the standard OfficeMetadata fields.
+	 * Examples: all <meta> tags in HTML, app.xml properties in DOCX, XMP dicts in PDF.
+	 */
+	nativeProperties?: Record<string, any>;
+}
+/**
+ * Contains out-of-band layout elements and templates that are not part of the main document flow.
+ */
+export interface OfficeAuxiliaryContent {
+	/** Headers extracted from the document. */
+	headers?: OfficeContentNode[];
+	/** Footers extracted from the document. */
+	footers?: OfficeContentNode[];
+	/** Slide Masters extracted from presentations. */
+	slideMasters?: OfficeContentNode[];
 }
 /**
- * The Abstract Syntax Tree (AST) returned by the parser.
- * This is the root data structure representing the entire parsed document.
+ * The Root Abstract Syntax Tree (AST) representing a parsed Office Document.
+ * This is the ultimate output of `OfficeParser.parseOffice()`.
  *
- * The AST provides a format-agnostic representation of the document that can be easily
- * processed, transformed, or converted to other formats. It preserves the document's
- * structure, content, formatting, and metadata while abstracting away format-specific details.
+ * DESIGN PHILOSOPHY:
+ * The AST is designed to be a universal, format-agnostic representation of document content.
+ * Whether the input was a PDF, DOCX, XLSX, Markdown, or HTML file, the resulting AST
+ * uses the same consistent structure (`OfficeContentNode` trees).
+ *
+ * ### Key Top-Level Properties:
+ * - `metadata`: Document-level properties (author, title, stats).
+ * - `content`: The main sequential flow of the document (paragraphs, tables, slides, sheets).
+ * - `attachments`: Extracted binary assets (images, embedded files).
+ * - `auxiliary`: Out-of-band layout/template elements (headers, footers, slide masters).
  *
  * @example
  * ```typescript
@@ -1563,6 +1766,12 @@ export interface OfficeParserAST {
 	 * @example [{ type: 'paragraph', text: 'Hello' }, { type: 'heading', text: 'Chapter 1' }]
 	 */
 	content: OfficeContentNode[];
+	/**
+	 * Out-of-band layout and template elements that are not part of the main text flow.
+	 * Extracted only if the respective `ignore...` config flags are false.
+	 * Contains elements like `headers`, `footers`, and `slideMasters`.
+	 */
+	auxiliary?: OfficeAuxiliaryContent;
 	/**
 	 * Attachments extracted from the document (images, charts, embedded files).
 	 * Only populated when `config.extractAttachments` is true.
@@ -1606,7 +1815,7 @@ export interface OfficeParserAST {
 	 * const md = await ast.to('md');
 	 * ```
 	 */
-	to<T extends this, D extends SupportedDestination<T["type"]>>(this: T, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult>;
+	to<T extends this, D extends SupportedDestination<T["type"]>>(this: T, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult<D>>;
 }
 /**
  * Main parser class providing office document parsing functionality.
@@ -1653,7 +1862,7 @@ export declare class OfficeParser {
 	 * });
 	 *
 	 * // Parse a Buffer with OCR enabled
-	 * const buffer = await fetch('document.pdf').then(r => r.arrayBuffer());
+	 * const buffer = await retrieveData('document.pdf').then(r => r.arrayBuffer());
 	 * const ast = await OfficeParser.parseOffice(buffer, {
 	 *   ocr: true,
 	 *   ocrLanguage: 'eng+fra'
@@ -1678,6 +1887,10 @@ export declare class OfficeParser {
  * Main generator class providing document conversion functionality.
  */
 export declare class OfficeGenerator {
+	/**
+	 * Normalizes format aliases (e.g., 'txt' to 'text', 'markdown' to 'md') to standard internal formats.
+	 */
+	static normalizeDestination(dest: string): UniversalGeneratorFormat;
 	/**
 	 * Generates a file of the specified type from an AST.
 	 * This is the single source of truth for generation logic.
@@ -1690,7 +1903,7 @@ export declare class OfficeGenerator {
 	 */
 	static generate<T extends SupportedFileType, D extends SupportedDestination<T>>(ast: OfficeParserAST & {
 		type: T;
-	}, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult>;
+	}, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult<D>>;
 }
 /**
  * Utility type to infer the file type from a file path string literal.