@thasmorato/docx-parser
Version:
A modern JavaScript library for parsing and processing Microsoft Word DOCX documents with support for both buffer and stream operations. Features incremental parsing, checkbox detection, footnote support, and document validation.
261 lines (253 loc) • 8.54 kB
text/typescript
import { ReadStream } from 'node:fs';
import { Readable } from 'node:stream';
import { ReadableStream } from 'node:stream/web';
interface BaseElement {
type: string;
id?: string;
position: {
page: number;
section: number;
order: number;
};
error?: {
type: 'warning' | 'error';
message: string;
recoverable: boolean;
};
}
interface MetadataElement extends BaseElement {
type: 'metadata';
content: {
title?: string;
author?: string;
subject?: string;
keywords?: string[];
created?: Date;
modified?: Date;
pages?: number;
words?: number;
};
}
interface ParagraphElement extends BaseElement {
type: 'paragraph';
content: string;
formatting?: {
bold?: boolean;
italic?: boolean;
underline?: boolean;
fontSize?: number;
fontFamily?: string;
color?: string;
alignment?: 'left' | 'center' | 'right' | 'justify';
indent?: number;
lineSpacing?: number;
};
hyperlinks?: Array<{
text: string;
url: string;
start: number;
end: number;
}>;
}
interface ImageElement extends BaseElement {
type: 'image';
content: Buffer;
metadata: {
filename?: string;
format: 'png' | 'jpg' | 'gif' | 'svg' | 'wmf' | 'emf';
width: number;
height: number;
dpi?: number;
};
positioning?: {
inline: boolean;
x?: number;
y?: number;
wrap?: 'square' | 'tight' | 'through' | 'topBottom';
};
}
interface TableRow {
cells: TableCell[];
height?: number;
isHeader?: boolean;
}
interface TableCell {
content: string;
colspan?: number;
rowspan?: number;
formatting?: {
backgroundColor?: string;
textAlign?: 'left' | 'center' | 'right';
verticalAlign?: 'top' | 'middle' | 'bottom';
};
}
interface TableElement extends BaseElement {
type: 'table';
content: TableRow[];
formatting?: {
borders?: boolean;
borderStyle?: string;
width?: number | 'auto';
alignment?: 'left' | 'center' | 'right';
};
}
interface ListElement extends BaseElement {
type: 'list';
content: string[];
listType: 'bullet' | 'number';
level: number;
}
interface HeaderElement extends BaseElement {
type: 'header';
content: string;
level: 1 | 2 | 3 | 4 | 5 | 6;
}
interface FooterElement extends BaseElement {
type: 'footer';
content: string;
}
interface PageBreakElement extends BaseElement {
type: 'pageBreak';
content: null;
}
interface SectionElement extends BaseElement {
type: 'section';
content: string;
sectionType: 'header' | 'footer' | 'body';
}
type DocumentElement = MetadataElement | ParagraphElement | ImageElement | TableElement | ListElement | HeaderElement | FooterElement | PageBreakElement | SectionElement;
interface ParseOptions {
includeMetadata?: boolean;
includeImages?: boolean;
includeTables?: boolean;
includeHeaders?: boolean;
includeFooters?: boolean;
imageFormat?: 'buffer' | 'base64' | 'stream';
maxImageSize?: number;
preserveFormatting?: boolean;
normalizeWhitespace?: boolean;
chunkSize?: number;
concurrent?: boolean;
}
interface ValidationResult {
isValid: boolean;
errors: Array<{
code: string;
message: string;
severity: 'error' | 'warning';
position?: {
line: number;
column: number;
};
}>;
}
declare class DocxParseError extends Error {
readonly position?: {
line: number;
column: number;
} | undefined;
readonly code?: string | undefined;
constructor(message: string, position?: {
line: number;
column: number;
} | undefined, code?: string | undefined);
}
/**
* Parse a DOCX document from a Buffer, yielding elements incrementally
*/
declare function parseDocx(buffer: Buffer, options?: ParseOptions): AsyncGenerator<DocumentElement>;
/**
* Parse a DOCX document from a ReadStream (Node.js), yielding elements incrementally
*/
declare function parseDocxStream(stream: ReadStream, options?: ParseOptions): AsyncGenerator<DocumentElement>;
/**
* Parse a DOCX document from a Node.js Readable stream (from HTTP requests), yielding elements incrementally
*/
declare function parseDocxHttpStream(stream: Readable, options?: ParseOptions): AsyncGenerator<DocumentElement>;
/**
* Parse a DOCX document from a ReadableStream (Web API), yielding elements incrementally
*/
declare function parseDocxWebStream(stream: ReadableStream, options?: ParseOptions): AsyncGenerator<DocumentElement>;
/**
* Parse a DOCX document from a file path, yielding elements incrementally
*/
declare function parseDocxFile(filePath: string, options?: ParseOptions): AsyncGenerator<DocumentElement>;
/**
* Parse a DOCX document and return all elements as an array (non-streaming)
*/
declare function parseDocxToArray(source: Buffer | ReadStream | ReadableStream | Readable, options?: ParseOptions): Promise<DocumentElement[]>;
/**
* Extract only text content from a DOCX document
*/
declare function extractText(source: Buffer | ReadStream | ReadableStream | Readable, options?: {
preserveFormatting?: boolean;
}): Promise<string>;
/**
* Extract only images from a DOCX document
*/
declare function extractImages(source: Buffer | ReadStream | ReadableStream | Readable): AsyncGenerator<DocumentElement>;
/**
* Get document metadata only
*/
declare function getMetadata(source: Buffer | ReadStream | ReadableStream | Readable): Promise<DocumentElement['content']>;
/**
* Parse a DOCX document from a Node.js Readable stream (from stream module), yielding elements incrementally
* This is a generic function for any Node.js Readable stream, including custom streams, transformed streams, etc.
*/
declare function parseDocxReadable(stream: Readable, options?: ParseOptions): AsyncGenerator<DocumentElement>;
/**
* StreamAdapter - Class for converting normal ReadStream to web ReadableStream
*/
declare class StreamAdapter {
/**
* Converts a Node.js ReadStream to web ReadableStream
* @param readStream - Node.js read stream (fs.ReadStream)
* @returns Web API ReadableStream
*/
static toWebStream(readStream: ReadStream): ReadableStream<Uint8Array>;
/**
* Checks if it's a Web ReadableStream
*/
private static isWebReadableStream;
/**
* Checks if it's a Node.js Readable stream
*/
private static isNodeReadableStream;
/**
* Converts Node.js Readable stream to Buffer
*/
private static nodeStreamToBuffer;
/**
* Converts Web ReadableStream to Buffer
*/
private static webStreamToBuffer;
/**
* Converts ReadableStream (Web or Node.js) to Buffer
* Automatically detects stream type and uses appropriate conversion
* @param stream - Web ReadableStream or Node.js Readable stream
* @returns Promise that resolves to Buffer
*/
static toBuffer(stream: ReadableStream<Uint8Array> | Readable): Promise<Buffer>;
/**
* Creates a web ReadableStream from a Buffer
* @param buffer - Buffer to be converted
* @returns Web ReadableStream
*/
static fromBuffer(buffer: Buffer): ReadableStream<Uint8Array>;
/**
* Converts Node.js Readable stream to Web ReadableStream
* Useful for HTTP requests (axios, fetch, etc)
* @param nodeStream - Node.js Readable stream
* @returns Web API ReadableStream
*/
static nodeToWebStream(nodeStream: Readable): ReadableStream<Uint8Array>;
}
interface ValidateDocumentUseCase {
validate(source: Buffer | ReadableStream): Promise<ValidationResult>;
}
declare class ValidateDocumentUseCaseImpl implements ValidateDocumentUseCase {
validate(source: Buffer | ReadableStream): Promise<ValidationResult>;
private hasValidZipSignature;
}
declare const VERSION = "1.0.0";
export { type DocumentElement, DocxParseError, type FooterElement, type HeaderElement, type ImageElement, type ListElement, type MetadataElement, type PageBreakElement, type ParagraphElement, type ParseOptions, type SectionElement, StreamAdapter, type TableElement, VERSION, ValidateDocumentUseCaseImpl, type ValidationResult, extractImages, extractText, getMetadata, parseDocx, parseDocxFile, parseDocxHttpStream, parseDocxReadable, parseDocxStream, parseDocxToArray, parseDocxWebStream };