officeparser 6.1.1 → 7.0.0

package/dist/types.d.ts

@@ -1,3 +1,71 @@
+/**
+ * Standard error types for OfficeParser.
+ * Use these to identify the kind of error being reported.
+ */
+export declare enum OfficeErrorType {
+    /** Unsupported file extension */
+    EXTENSION_UNSUPPORTED = "EXTENSION_UNSUPPORTED",
+    /** File appears to be corrupted or malformed */
+    FILE_CORRUPTED = "FILE_CORRUPTED",
+    /** File could not be found at the specified path */
+    FILE_DOES_NOT_EXIST = "FILE_DOES_NOT_EXIST",
+    /** Specified location/directory is not reachable or is a directory */
+    LOCATION_NOT_FOUND = "LOCATION_NOT_FOUND",
+    /** Arguments passed to the function are missing or invalid */
+    IMPROPER_ARGUMENTS = "IMPROPER_ARGUMENTS",
+    /** Error occurred while reading or processing file buffers */
+    IMPROPER_BUFFERS = "IMPROPER_BUFFERS",
+    /** Input type is not a supported type (string, Buffer, ArrayBuffer) */
+    INVALID_INPUT = "INVALID_INPUT",
+    /** PDF worker source is missing (required in browser) */
+    PDF_WORKER_MISSING = "PDF_WORKER_MISSING",
+    /** Attempted to use Node.js-only features in a browser environment */
+    FEATURE_NOT_SUPPORTED_IN_BROWSER = "FEATURE_NOT_SUPPORTED_IN_BROWSER",
+    /** Style mapping string is malformed */
+    INVALID_STYLE_MAPPING = "INVALID_STYLE_MAPPING",
+    /** Selector in style mapping is invalid */
+    INVALID_SELECTOR = "INVALID_SELECTOR",
+    /** Output mapping in style mapping is invalid */
+    INVALID_OUTPUT_MAPPING = "INVALID_OUTPUT_MAPPING",
+    /** Semantic chunking strategy is selected but no embedding function is provided */
+    MISSING_EMBEDDING_FUNCTION = "MISSING_EMBEDDING_FUNCTION"
+}
+/**
+ * Standard warning types for OfficeParser.
+ * Use these for reporting non-fatal issues or performance tips.
+ */
+export declare enum OfficeWarningType {
+    /** Performance advice (e.g., Rosetta translation on Mac) */
+    PERFORMANCE_TIP = "PERFORMANCE_TIP",
+    /** OCR processing failed for an attachment */
+    OCR_FAILED = "OCR_FAILED",
+    /** Extraction of structured chart data failed */
+    CHART_DATA_EXTRACTION_FAILED = "CHART_DATA_EXTRACTION_FAILED",
+    /** Automatic worker path failed, falling back to CDN */
+    PDF_WORKER_FALLBACK = "PDF_WORKER_FALLBACK",
+    /** General attachment extraction failure */
+    ATTACHMENT_EXTRACTION_FAILED = "ATTACHMENT_EXTRACTION_FAILED",
+    /** Failed to load a specific page in a multi-page document */
+    PAGE_LOAD_FAILED = "PAGE_LOAD_FAILED",
+    /** Failed to load a required dynamic dependency */
+    DEPENDENCY_LOAD_FAILED = "DEPENDENCY_LOAD_FAILED",
+    /** Failed to extract images from a source */
+    IMAGE_EXTRACTION_FAILED = "IMAGE_EXTRACTION_FAILED",
+    /** Failed to extract annotations from a document */
+    ANNOTATION_EXTRACTION_FAILED = "ANNOTATION_EXTRACTION_FAILED",
+    /** Failed to process an extracted image bitmap */
+    IMAGE_PROCESSING_FAILED = "IMAGE_PROCESSING_FAILED",
+    /** Warning about limitations of browser-based generation */
+    BROWSER_GENERATION_LIMITATION = "BROWSER_GENERATION_LIMITATION",
+    /** Specified sheet range in Excel/ODS export was not found */
+    SHEET_RANGE_NOT_FOUND = "SHEET_RANGE_NOT_FOUND",
+    /** Buffer content type does not match the provided or expected file extension */
+    BUFFER_TYPE_MISMATCH = "BUFFER_TYPE_MISMATCH",
+    /** 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"
+}
 /**
  * Configuration options for OCR.
  */
@@ -16,16 +84,19 @@ export interface OcrConfig {
     /**
      * Path to the Tesseract worker script.
      * Primarily used for offline/air-gapped environments.
+     * Default is ''.
      */
     workerPath?: string;
     /**
      * Path to the Tesseract core script.
      * Primarily used for offline/air-gapped environments.
+     * Default is ''.
      */
     corePath?: string;
     /**
      * Path for Tesseract language files (traineddata).
      * Primarily used for offline/air-gapped environments.
+     * Default is ''.
      */
     langPath?: string;
     /**
@@ -40,10 +111,17 @@ export interface OcrConfig {
  */
 export interface OfficeParserConfig {
     /**
+     * @deprecated Use `onWarning` instead.
      * Flag to show all the logs to console in case of an error irrespective of your own handling.
      * Default is false.
      */
     outputErrorToConsole?: boolean;
+    /**
+     * Callback for warnings or non-fatal errors encountered during parsing.
+     * Allows you to capture issues like OCR failures or attachment extraction errors
+     * without stopping the parsing process.
+     */
+    onWarning?: (issue: OfficeIssue) => void;
     /**
      * The delimiter used for every new line in places that allow multiline text like word.
      * Default is \n.
@@ -112,7 +190,7 @@ export interface OfficeParserConfig {
      * The URL/path to the PDF.js worker script.
      *
      * **Mandatory** when using PDF parsing in browser environments to avoid worker configuration errors.
-     * If not provided, it defaults to `https://unpkg.com/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs`.
+     * If not provided, it defaults to `https://cdn.jsdelivr.net/npm/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs`.
      * You can override this with your own local path or a different CDN link.
      */
     pdfWorkerSrc?: string;
@@ -123,19 +201,655 @@ export interface OfficeParserConfig {
      * Default is false
      */
     includeBreakNodes?: boolean;
+    /**
+     * Flag to ignore all internal (anchor) links during parsing.
+     * When true, all bookmarks, cross-references, and internal document jumps are stripped
+     * from the AST. Only external URLs will be preserved.
+     *
+     * Use this if you want a "flat" document without any internal interactivity.
+     *
+     * Default is false.
+     */
+    ignoreInternalLinks?: boolean;
+    /**
+     * Optional hint for the file format.
+     * When a Buffer or ArrayBuffer is passed, the parser relies on magic bytes to detect the file type.
+     * Text-based formats like 'md', 'html', and 'csv' lack reliable magic bytes.
+     * If you are parsing these formats from a Buffer, you must provide this fileType hint.
+     *
+     * This is authoritative and is used to determine the file type, so it should be accurate.
+     * If provided, this bypasses the magic bytes detection and the file extension-based detection either way.
+     *
+     * Default is null.
+     */
+    fileType?: SupportedFileType | null;
+    /**
+     * Custom delimiter for CSV files.
+     * Defaults to ',' but can be overridden (e.g., ';', '\t').
+     */
+    csvDelimiter?: string;
+}
+/**
+ * A fully-populated parser configuration containing all options.
+ * Used internally for merging and resolution.
+ */
+export type FullOfficeParserConfig = DeepRequired<OfficeParserConfig>;
+/**
+ * Represents a single issue (warning, error, or info) generated during document processing.
+ */
+export interface OfficeIssue {
+    /** The severity of the issue. */
+    type: 'warning' | 'info' | 'error';
+    /** Human-readable message text. */
+    message: string;
+    /** The specific AST node that triggered this issue, if applicable. */
+    node?: OfficeContentNode;
+    /** A unique error code for programmatic handling. */
+    code: OfficeWarningType | OfficeErrorType;
+    /** Optional additional context or original error object. */
+    details?: any;
+}
+/**
+ * The result of a document conversion operation.
+ */
+export interface ConversionResult<D extends string = 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;
+    /** A collection of issues (warnings/infos) generated during the process. */
+    messages: OfficeIssue[];
+}
+/**
+ * Universal formats supported by all source types for generation.
+ */
+export type UniversalGeneratorFormat = 'text' | 'md' | 'html' | 'pdf' | 'csv' | 'rtf' | 'chunks';
+/**
+ * Allowed destination formats for a given source type.
+ * Currently, all generators are universal across all source formats.
+ */
+export type SupportedDestination<_T extends SupportedFileType = SupportedFileType> = UniversalGeneratorFormat;
+/**
+ * Configuration options for the OfficeGenerator.
+ */
+/**
+ * Common configuration options for all generators.
+ */
+export interface CommonGeneratorConfig {
+    /**
+     * Callback called for every node during generation.
+     * Allows users to modify nodes before processing, completely override rendering, or filter them out.
+     *
+     * #### Callback Capabilities:
+     * 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.
+     */
+    onNode?: (node: OfficeContentNode) => string | false | Promise<string | false | void> | void;
+    /**
+     * Callback for warnings, non-fatal errors, or issues encountered during generation.
+     * Allows the process to continue while reporting skipping or approximation of content.
+     */
+    onWarning?: (issue: OfficeIssue) => void;
+    /**
+     * Map document styles (e.g., 'Heading 1', 'Intense Quote') to specific semantic elements.
+     *
+     * DESIGN PHILOSOPHY:
+     * This is the primary way to customize how the library interprets the visual
+     * structure of your source documents.
+     *
+     * To disable all semantic translation and use raw AST types only,
+     * set `ignoreDefaultStyleMap: true` and leave `styleMap` empty.
+     *
+     * It supports two formats:
+     *
+     * 1. LEGACY STRING DSL:
+     * Simple "selector => output" syntax. Highly compatible with mammoth.js style maps.
+     * @example ["p[style-name='Heading 1'] => h1"]
+     * @example ["p[style='Quote'] => blockquote"]
+     *
+     * 2. STRUCTURED OBJECTS (Recommended):
+     * More powerful and strictly typed. Ideal for complex logic or when you
+     * need to apply specific classes/attributes for the HTML generator.
+     * @example
+     * [
+     *   {
+     *     selector: { nodeType: 'paragraph', attributes: { style: 'Heading 1' } },
+     *     output: { tag: 'h1', classes: ['main-title'], attributes: { id: 'top' } }
+     *   }
+     * ]
+     *
+     * Note: This property works in conjunction with `ignoreDefaultStyleMap`.
+     * Defaults to a robust built-in map that covers common standard Office styles.
+     */
+    styleMap?: string[] | StructuredStyleMapping[];
+    /**
+     * Whether to include visual formatting like font size, font family, and colors in the output.
+     * Set to false for clean, semantic output.
+     * Defaults to true.
+     */
+    includeFormatting?: boolean;
+    /**
+     * Whether to automatically generate unique slug-based IDs for headings.
+     * Useful for table-of-contents and anchor links.
+     * Defaults to true.
+     */
+    generateIds?: boolean;
+    /**
+     * Whether to render document metadata (title, author, etc.) as visible content
+     * in the generated output (e.g., a header block in HTML or plain text).
+     * Structural metadata (HTML <meta> tags, Markdown YAML frontmatter) is always included.
+     * Defaults to false.
+     */
+    renderMetadata?: boolean;
+    /**
+     * Whether to ignore the built-in default style mappings (e.g. "Heading 1" -> h1).
+     * Set to true if you want full control over style mapping.
+     * Defaults to false.
+     */
+    ignoreDefaultStyleMap?: boolean;
+    /**
+     * Whether to include images in the generated output.
+     * Defaults to true.
+     */
+    includeImages?: boolean;
+    /**
+     * Whether to include interactive charts in the generated output (HTML only).
+     * Defaults to true.
+     */
+    includeCharts?: boolean;
+    /**
+     * Whether to ignore all internal (anchor) links and anchor IDs during generation.
+     * When true, all bookmarks, cross-references, and internal document jumps are stripped.
+     * Specifically for Markdown, this removes the {#id} block from headings.
+     * Defaults to false.
+     */
+    ignoreInternalLinks?: boolean;
+}
+/**
+ * Destination-aware generator configuration.
+ * Restricts format-specific configurations to their respective destinations.
+ */
+/**
+ * Mapping of destination formats to their specific configuration interfaces.
+ */
+export interface GeneratorSubConfigMap {
+    html: HtmlGeneratorConfig;
+    md: MdGeneratorConfig;
+    pdf: PdfGeneratorConfig;
+    csv: CsvGeneratorConfig;
+    text: TextGeneratorConfig;
+    rtf: RtfGeneratorConfig;
+    chunks: ChunkingConfig;
+}
+/**
+ * Configuration options for document generators.
+ *
+ * This interface is designed to be format-aware. When you specify a destination format
+ * (e.g., `OfficeGenerator.generate(ast, 'html', config)`), the generic parameter `D`
+ * ensures that only the relevant sub-configuration (e.g., `htmlConfig`) is available
+ * for type checking.
+ *
+ * @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);
+};
+/**
+ * Configuration options for the OfficeConverter.
+ * Combines relevant parser and generator settings for a seamless one-step conversion.
+ *
+ * @template D The destination format string.
+ */
+/**
+ * Configuration options for the OfficeConverter.
+ * Combines general generator settings with a specific subset of parser settings.
+ *
+ * @template D The destination format string.
+ * @template T The source file type.
+ */
+export type OfficeConverterConfig<D extends string = string, T extends SupportedFileType = SupportedFileType> = {
+    /**
+     * Specific configuration for the source parsing phase.
+     */
+    parseConfig?: OfficeParserConfig & {
+        fileType?: T;
+    };
+    /**
+     * Specific configuration for the destination generation phase.
+     */
+    generatorConfig?: GeneratorConfig<D>;
+    /**
+     * Callback for warnings or non-fatal errors encountered during the entire conversion process.
+     * This is passed to both the parser and the generator.
+     * If provided, this takes precedence over callbacks inside parseConfig or generatorConfig.
+     */
+    onWarning?: (issue: OfficeIssue) => void;
+};
+/**
+ * Deeply required type helper.
+ */
+export type DeepRequired<T> = T extends Function | Date | Buffer | RegExp ? T : T extends Array<infer U> ? Array<DeepRequired<U>> : T extends object ? {
+    [P in keyof T]-?: DeepRequired<T[P]>;
+} : T;
+/**
+ * A fully-populated generator configuration containing all sub-configs.
+ * Used internally for merging and resolution.
+ * `chunksConfig` is typed as `ChunkingConfig` directly (not DeepRequired) because
+ * it is a discriminated union whose members cannot be uniformly deep-required.
+ */
+export type FullGeneratorConfig = DeepRequired<CommonGeneratorConfig & {
+    [K in keyof Omit<GeneratorSubConfigMap, 'chunks'> as `${K}Config`]: GeneratorSubConfigMap[K];
+}> & {
+    chunksConfig: ChunkingConfig;
+};
+/**
+ * Configuration options for HTML generation.
+ */
+export interface HtmlGeneratorConfig {
+    /**
+     * Whether to wrap the output in a full HTML document structure (e.g., <html>, <head>, etc.).
+     * Defaults to true.
+     */
+    standalone?: boolean;
+    /**
+     * URL for the Chart.js library to use when 'includeCharts' is true.
+     * Defaults to 'https://cdn.jsdelivr.net/npm/chart.js'.
+     */
+    chartJsSrc?: string;
+}
+/**
+ * Configuration options for PDF generation.
+ * Maps closely to Puppeteer's PDF options.
+ */
+export interface PdfGeneratorConfig {
+    /** Paper format. Defaults to 'A4'. */
+    format?: 'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6' | 'Letter' | 'Legal' | 'Tabloid' | 'Ledger' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6';
+    /** Paper width, accepts values labeled with units (e.g., '5in', '3cm') or numbers (in pixels). */
+    width?: string | number;
+    /** Paper height, accepts values labeled with units (e.g., '5in', '3cm') or numbers (in pixels). */
+    height?: string | number;
+    /** Whether to print in landscape orientation. Defaults to false. */
+    landscape?: boolean;
+    /** Whether to print background graphics. Defaults to true. */
+    printBackground?: boolean;
+    /** Scale of the webpage rendering. Defaults to 1. */
+    scale?: number;
+    /** Paper margins. */
+    margin?: {
+        top?: string | number;
+        right?: string | number;
+        bottom?: string | number;
+        left?: string | number;
+    };
+    /** Whether to display header and footer. Defaults to false. */
+    displayHeaderFooter?: boolean;
+    /** HTML template for the print header. */
+    headerTemplate?: string;
+    /** HTML template for the print footer. */
+    footerTemplate?: string;
+    /**
+     * Optional Puppeteer launch options for Node.js environment.
+     * Useful for setting custom executable paths or args in CI/CD.
+     */
+    launchOptions?: any;
+}
+/**
+ * Structured style mapping definition for the StyleMapper.
+ *
+ * DESIGN PHILOSOPHY: "Semantic Translation"
+ * -----------------------------------------
+ * Office documents (Word, RTF, PPTX) often use custom or localized style names
+ * (e.g., "Heading 1" in English vs "Titre 1" in French, or "MyCompany-Quote").
+ *
+ * This interface allows you to create a "semantic bridge" between these arbitrary
+ * source styles and a universal vocabulary of document elements.
+ *
+ * WHY USE HTML TAGS FOR NON-HTML OUTPUT?
+ * --------------------------------------
+ * We use HTML tags (`h1`, `blockquote`, `code`, `pre`) as a "Universal Intermediate
+ * Language". By mapping a custom Word style to `blockquote`, you are defining its
+ * SEMANTIC MEANING rather than its physical appearance.
+ *
+ * Each generator then interprets this meaning natively:
+ * - HTML Generator: Directly renders the `<blockquote>` tag with your classes.
+ * - Markdown Generator: Sees 'blockquote' and renders the standard `> ` prefix.
+ * - Text Generator: Sees 'blockquote' and applies appropriate structural indentation.
+ */
+export interface StructuredStyleMapping {
+    /**
+     * The criteria used to identify which AST nodes should be transformed.
+     * Think of this as the "Source Filter".
+     */
+    selector: {
+        /**
+         * 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;
+        /**
+         * A dictionary of attributes to match on the node.
+         *
+         * The most common use case is matching the 'style' attribute from
+         * Word documents (e.g., { style: 'Intense Quote' }).
+         *
+         * Matchers:
+         * - Literal: `style: 'Heading 1'` matches exactly.
+         * - Operator: `{ value: 'Title', operator: '~=' }` matches if the word 'Title'
+         *   is found within the style name.
+         */
+        attributes?: Record<string, string | number | boolean | {
+            value: string | number | boolean;
+            operator: '=' | '~=';
+        }>;
+    };
+    /**
+     * The target representation for the matched node.
+     * Think of this as the "Semantic Meaning" you want to assign to the match.
+     */
+    output: {
+        /**
+         * The universal semantic tag (e.g., 'h1', 'h2', 'blockquote', 'code', 'pre', 'u').
+         * All generators use this tag to decide their native output syntax.
+         */
+        tag: string;
+        /**
+         * CSS classes to apply to the output.
+         * This is utilized by the HTML generator to allow for downstream CSS styling.
+         */
+        classes?: string[];
+        /**
+         * Key-value pair of HTML attributes (like 'id', 'data-*', or 'style') to apply.
+         * Primarily used by the HTML generator for high-fidelity conversion.
+         */
+        attributes?: Record<string, string>;
+        /**
+         * If true, prevents the generator from collapsing this element into
+         * adjacent elements of the same type.
+         *
+         * For example, multiple paragraphs mapped to 'blockquote' normally merge into
+         * one big blockquote. Setting `fresh: true` forces them to be separate blocks.
+         */
+        fresh?: boolean;
+    };
+}
+/**
+ * Configuration options for RTF generation.
+ */
+export interface RtfGeneratorConfig {
+}
+/**
+ * Configuration options for CSV generation.
+ */
+export interface CsvGeneratorConfig {
+    /**
+     * Range of sheets to export.
+     * Supports formats like "1", "1-3", "1,2", "1,3-5,7".
+     * 1-based indexing.
+     * Default is '' (all sheets).
+     */
+    sheets?: string;
+    /**
+     * Whether to merge all selected sheets into a single CSV.
+     * If false, returns a ZIP archive containing individual CSV files.
+     * Defaults to false.
+     */
+    mergeSheets?: boolean;
+    /**
+     * Custom delimiter for CSV files.
+     * Defaults to ','.
+     */
+    columnDelimiter?: string;
+}
+/**
+ * Configuration options for Markdown generation.
+ */
+export interface MdGeneratorConfig {
+    /**
+     * Whether to fallback to HTML tags for features not supported by standard Markdown.
+     *
+     * Markdown has limited support for complex document structures. This flag controls how
+     * the generator handles features that cannot be represented in pure Markdown:
+     *
+     * 1. If a feature is NOT supported natively by Markdown (e.g., nested tables, text alignment,
+     *    underline, subscript/superscript):
+     *    - If true: The generator will use HTML tags (<u>, <sub>, <div>, <table>, etc.) to
+     *      maintain high fidelity.
+     *    - If false: The generator will skip or simplify the feature (e.g., ignoring alignment,
+     *      skipping underline, or hoisting nested tables out of their cells).
+     *
+     * 2. If a feature IS supported by Markdown but a higher quality version is possible
+     *    via HTML (e.g., tables with merged cells):
+     *    - If true: Use HTML for better fidelity.
+     *    - If false: Use native Markdown syntax (e.g., a standard GFM table grid).
+     *
+     * Defaults to true.
+     */
+    fallbackToHtml?: boolean;
+}
+/**
+ * Configuration options for plain text generation.
+ */
+export interface TextGeneratorConfig {
+    /**
+     * The delimiter used for every new line.
+     * Defaults to '\n'.
+     */
+    newlineDelimiter?: string;
+    /**
+     * Whether to attempt to preserve the original document layout.
+     * If true, tables will be rendered with separators and aligned columns.
+     * If false, output will be a flat stream of text nodes.
+     * Defaults to false.
+     */
+    preserveLayout?: boolean;
+}
+/**
+ * The strategy used for chunking a document for RAG pipelines.
+ * - 'fixed-size': Traditional character/token count based splitting.
+ * - 'document-structure': Leverages the AST to split at natural document boundaries.
+ * - 'semantic': Uses embedding similarity to find natural topic breakpoints.
+ */
+export type ChunkingStrategy = 'fixed-size' | 'document-structure' | 'semantic';
+/**
+ * Base configuration applicable to all chunking strategies.
+ */
+export interface BaseChunkingConfig {
+    /**
+     * The strategy used for chunking.
+     * Default is 'document-structure'.
+     */
+    strategy?: ChunkingStrategy;
+    /**
+     * A function that measures the size of a text string.
+     * Defaults to character count: `(text) => text.length`.
+     * Override with a token counter (e.g., `tiktoken`) for strict LLM context window adherence.
+     */
+    lengthFunction?: (text: string) => number;
+    /**
+     * Whether to strip leading/trailing whitespace from each chunk.
+     * Default is true.
+     */
+    stripWhitespace?: boolean;
+    /**
+     * Whether to include rich AST metadata (page number, slide number, heading, etc.)
+     * in the generated chunk objects.
+     * Default is true.
+     */
+    includeMetadata?: boolean;
+    /**
+     * Whether to include the starting character index of each chunk
+     * relative to the whole document. Useful for UI text highlighting.
+     * Default is false.
+     */
+    addStartIndex?: boolean;
+    /**
+     * Optional custom regex (as string or RegExp object) to identify sentence boundaries.
+     * Use this for languages or specific document types that require custom splitting logic.
+     * If provided, it overrides or augments the default segmenter.
+     * @example /[。？！]/
+     */
+    sentenceBoundaryRegex?: string | RegExp;
+    /**
+     * Optional list of abbreviations to ignore when splitting text into sentences.
+     * These words, if followed by a period, will not be treated as sentence boundaries.
+     * Use this to handle language-specific or domain-specific abbreviations.
+     * @example ["Inc", "Ltd", "approx"]
+     */
+    abbreviations?: string[];
+}
+/**
+ * Configuration for Fixed-Size Chunking.
+ * Cuts text based on a maximum size limit with an optional overlap.
+ * This is equivalent to LangChain's `RecursiveCharacterTextSplitter`.
+ */
+export interface FixedSizeChunkingConfig extends BaseChunkingConfig {
+    strategy: 'fixed-size';
+    /**
+     * Maximum size of the chunk, measured by `lengthFunction`.
+     * Default is 1000 characters.
+     */
+    chunkSize?: number;
+    /**
+     * Number of characters/tokens to overlap between consecutive chunks
+     * to avoid losing context at boundaries.
+     * Rule of thumb: ~10–20% of `chunkSize`.
+     * Default is 200.
+     */
+    chunkOverlap?: number;
+    /**
+     * Ordered list of separators to try when splitting.
+     * The chunker tries each in order; if a split would exceed `chunkSize`,
+     * it tries the next separator.
+     * Default is ['\n\n', '\n', ' ', ''].
+     */
+    separators?: string[];
+}
+/**
+ * Configuration for Document-Structure Chunking.
+ * Uses the officeParser AST to split at natural document boundaries like
+ * headings, paragraphs, slides, or pages. This is the recommended strategy
+ * as it preserves semantic context from the document's own structure.
+ */
+export interface DocumentStructureChunkingConfig extends BaseChunkingConfig {
+    strategy: 'document-structure';
+    /**
+     * The primary structural element at which to force a chunk boundary.
+     * - 'paragraph': Never cross a paragraph boundary (finest-grained, most precise).
+     * - 'heading': Split at every heading change.
+     * - 'page': Chunks never span multiple pages (PDF only).
+     * - 'slide': Chunks never span multiple slides (PPTX/ODP only).
+     * - 'sheet': Chunks never span multiple sheets (XLSX/ODS only).
+     * Default is 'paragraph'.
+     */
+    splitBy?: 'page' | 'slide' | 'sheet' | 'heading' | 'paragraph';
+    /**
+     * Maximum size of a chunk (measured by `lengthFunction`).
+     * If a single structural unit (e.g., one paragraph) exceeds this limit,
+     * it will be further split using a recursive character splitter.
+     * Default is 1000 characters.
+     */
+    maxChunkSize?: number;
+    /**
+     * How to handle table nodes when splitting.
+     * - 'row': Split by rows, REPEATING the header row in every chunk so the LLM
+     *   always understands what the columns mean. (Highly recommended for RAG)
+     * - 'flatten': Convert the table to plain text and split like a regular block.
+     * Default is 'row'.
+     */
+    tableSplitStrategy?: 'row' | 'flatten';
+}
+/**
+ * Configuration for Semantic Chunking.
+ * Uses an embedding model to detect topic shifts and create boundaries
+ * where content meaning naturally changes. Computationally expensive but
+ * produces the highest quality chunks.
+ */
+export interface SemanticChunkingConfig extends BaseChunkingConfig {
+    strategy: 'semantic';
+    /**
+     * A user-provided async function to generate vector embeddings for a text string.
+     * Required. Example: a wrapper around OpenAI's `text-embedding-3-small`.
+     * @example async (text) => await openai.embeddings.create({ input: text, model: 'text-embedding-3-small' }).then(r => r.data[0].embedding)
+     */
+    embeddingFunction: (text: string) => Promise<number[]>;
+    /**
+     * The cosine similarity threshold below which a chunk boundary is created.
+     * When the similarity between two adjacent sentences drops below this value,
+     * a new chunk starts. Higher = more splits, smaller chunks.
+     * Default is 0.8.
+     */
+    similarityThreshold?: number;
+    /**
+     * Maximum size of a chunk even if semantic similarity remains high.
+     * Prevents runaway chunks when an entire document is on one topic.
+     * Default is 2000 characters.
+     */
+    maxChunkSize?: number;
+    /**
+     * Number of surrounding sentences to include when computing similarity
+     * for a sentence. A larger window reduces noise from single odd sentences.
+     * Default is 1.
+     */
+    bufferSize?: number;
+    /**
+     * Number of sentences to process in a single batch when calling the embedding function.
+     * Higher values are faster but may trigger API rate limits.
+     * Default is 50.
+     */
+    embeddingBatchSize?: number;
+}
+/**
+ * Discriminated union of all chunking strategy configurations.
+ */
+export type ChunkingConfig = FixedSizeChunkingConfig | DocumentStructureChunkingConfig | SemanticChunkingConfig;
+/**
+ * Represents a single document chunk ready for a RAG (Retrieval-Augmented Generation) pipeline.
+ *
+ * Chunks are the result of splitting a document into smaller, semantically coherent
+ * pieces that fit within the context window of an LLM. Each chunk includes the
+ * extracted text and rich AST-derived metadata for citations and filtered retrieval.
+ */
+export interface OfficeChunk {
+    /** The text content of this chunk. This is what gets embedded. */
+    text: string;
+    /**
+     * Rich contextual metadata extracted from the AST.
+     * Use this to populate vector DB metadata fields for filtered retrieval
+     * and for LLM citations.
+     */
+    metadata: {
+        /** The source file format (e.g., 'docx', 'pptx', 'pdf'). */
+        sourceType: SupportedFileType;
+        /** Page number (1-based), if available (PDF). */
+        pageNumber?: number;
+        /** Slide number (1-based), if available (PPTX/ODP). */
+        slideNumber?: number;
+        /** Sheet name, if available (XLSX/ODS). */
+        sheetName?: string;
+        /** The text of the nearest heading above this chunk in the document. */
+        closestHeading?: string;
+        /** True if this chunk is part of a table split. */
+        isTableChunk?: boolean;
+        /** Extensible for user-defined metadata. */
+        [key: string]: any;
+    };
+    /** The start character index of this chunk in the full document text. Only set when `addStartIndex` is true. */
+    startIndex?: number;
+    /** The end character index of this chunk in the full document text. Only set when `addStartIndex` is true. */
+    endIndex?: number;
 }
 /**
  * Supported file types for parsing.
  */
-export type SupportedFileType = 'docx' | 'pptx' | 'xlsx' | 'odt' | 'odp' | 'ods' | 'pdf' | 'rtf';
+export type SupportedFileType = 'docx' | 'pptx' | 'xlsx' | 'odt' | 'odp' | 'ods' | 'pdf' | 'rtf' | 'md' | 'html' | 'csv';
 /**
  * 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';
+export type OfficeContentNodeType = 'paragraph' | 'heading' | 'table' | 'list' | 'text' | 'image' | 'chart' | 'drawing' | 'slide' | 'note' | 'sheet' | 'row' | 'cell' | 'page' | 'break' | 'code' | 'comment';
 /**
  * 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.oasis.opendocument.chart' | 'application/vnd.oasis.opendocument.spreadsheet' | 'application/vnd.oasis.opendocument.text' | 'application/vnd.oasis.opendocument.presentation';
+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 formatting options available for text content.
  * Represents common formatting attributes found in office documents (DOCX, RTF, PPTX, etc.).
@@ -224,6 +938,8 @@ export interface SlideMetadata {
     noteId?: string;
     /** The style of the slide. */
     style?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for a sheet in Excel.
@@ -233,6 +949,8 @@ export interface SheetMetadata {
     sheetName: string;
     /** The style of the sheet. */
     style?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Detailed indentation information for paragraphs and headings.
@@ -260,6 +978,8 @@ export interface HeadingMetadata {
     style?: string;
     /** Detailed indentation information. */
     paragraphIndentation?: IndentationMetadata;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for a paragraph.
@@ -271,6 +991,8 @@ export interface ParagraphMetadata {
     style?: string;
     /** Detailed indentation information. */
     paragraphIndentation?: IndentationMetadata;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for a list item.
@@ -310,6 +1032,8 @@ export interface ListMetadata {
      * @example "ListParagraph"
      */
     style?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for a table cell (primarily used in Excel/spreadsheet parsing).
@@ -338,6 +1062,8 @@ export interface CellMetadata {
     colSpan?: number;
     /** The style of the cell. */
     style?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for a chart node in the document.
@@ -350,6 +1076,8 @@ export interface ChartMetadata {
      * @example "chart1.xml"
      */
     attachmentName: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for an image node in the document.
@@ -368,6 +1096,14 @@ export interface ImageMetadata {
      * @example "Company logo"
      */
     altText?: string;
+    /**
+     * URL of the image if it is an external link.
+     * Typical for HTML or Markdown images that point to remote servers.
+     * @example "https://example.com/image.png"
+     */
+    url?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for PDF page nodes.
@@ -413,6 +1149,8 @@ export interface NoteMetadata {
      * @example "1", "2"
      */
     noteId?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
 }
 /**
  * Metadata for break nodes.
@@ -439,10 +1177,19 @@ export interface BreakMetadata {
      */
     clear?: 'all' | 'left' | 'none' | 'right';
 }
+/**
+ * Metadata for a code block.
+ */
+export interface CodeMetadata {
+    /** The programming language of the code block (e.g., 'typescript', 'python') */
+    language?: string;
+    /** Unique anchor IDs for internal linking. */
+    anchorIds?: string[];
+}
 /**
  * Union type for content metadata.
  */
-export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | undefined;
+export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | CodeMetadata | undefined;
 /**
  * Represents a node in the document content tree.
  * This is the core building block of the parsed document structure.
@@ -680,9 +1427,19 @@ export interface OfficeMetadata {
  * console.log(ast.metadata.author); // 'John Doe'
  * console.log(ast.content.length); // Number of top-level content nodes
  * console.log(ast.toText()); // Plain text representation
+ * console.log((await ast.to('md')).value); // Markdown representation
+ * console.log((await ast.to('html')).value); // HTML representation
+ * console.log((await ast.to('rtf')).value); // RTF representation
+ * console.log((await ast.to('csv')).value); // CSV representation
+ * console.log((await ast.to('chunks')).value); // Chunks representation
  * ```
  */
 export interface OfficeParserAST {
+    /**
+     * The original configuration used to parse this document.
+     * This includes options like OCR settings, delimiter choices, and filtering flags.
+     */
+    config: OfficeParserConfig;
     /**
      * The type of the parsed file.
      * Indicates which parser was used and what format the input was in.
@@ -717,7 +1474,12 @@ export interface OfficeParserAST {
      * @example [{ type: 'image', mimeType: 'image/png', data: 'base64...', name: 'image1.png' }]
      */
     attachments: OfficeAttachment[];
+    /** Any warnings or non-fatal issues encountered during parsing. */
+    warnings: OfficeIssue[];
     /**
+     * @deprecated Use `.to('text')` instead.
+     * Note: This method is synchronous, while the new `.to()` method is asynchronous.
+     *
      * Converts the entire AST to plain text.
      * This method flattens the document structure and returns just the text content,
      * stripping out all formatting, metadata, and structure.
@@ -732,4 +1494,18 @@ export interface OfficeParserAST {
      * ```
      */
     toText(): string;
+    /**
+     * Converts this AST to the specified destination format.
+     * This is the recommended way to convert the AST to different formats.
+     *
+     * @param destination The target format (e.g., 'text', 'md', 'html', 'pdf').
+     * @param config Optional configuration for the generator.
+     * @returns A promise resolving to the generated content (string or Buffer).
+     * @example
+     * ```typescript
+     * const html = await ast.to('html', { includeFormatting: false });
+     * const md = await ast.to('md');
+     * ```
+     */
+    to<T extends this, D extends SupportedDestination<T['type']>>(this: T, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult>;
 }