@cj-tech-master/excelts 8.0.0 → 8.1.0

package/dist/cjs/modules/pdf/reader/pdf-parser.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * PDF object parser.
+ *
+ * Parses PDF tokens into typed PDF objects: dictionaries, arrays, strings,
+ * numbers, booleans, names, null, indirect references, and streams.
+ *
+ * @see PDF Reference 1.7, Chapter 3 - Objects
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPdfRef = isPdfRef;
+exports.isPdfStream = isPdfStream;
+exports.isPdfDict = isPdfDict;
+exports.isPdfArray = isPdfArray;
+exports.dictGetName = dictGetName;
+exports.dictGetNumber = dictGetNumber;
+exports.dictGetBool = dictGetBool;
+exports.dictGetDict = dictGetDict;
+exports.dictGetArray = dictGetArray;
+exports.dictGetRef = dictGetRef;
+exports.dictGetBytes = dictGetBytes;
+exports.dictGetString = dictGetString;
+exports.decodePdfStringBytes = decodePdfStringBytes;
+exports.parseObject = parseObject;
+exports.parseObjectFromToken = parseObjectFromToken;
+const errors_1 = require("../errors");
+// =============================================================================
+// Type Guards
+// =============================================================================
+function isPdfRef(obj) {
+    return obj !== null && typeof obj === "object" && "type" in obj && obj.type === "ref";
+}
+function isPdfStream(obj) {
+    return obj !== null && typeof obj === "object" && "type" in obj && obj.type === "stream";
+}
+function isPdfDict(obj) {
+    return obj instanceof Map;
+}
+function isPdfArray(obj) {
+    return Array.isArray(obj);
+}
+// =============================================================================
+// Dictionary Helpers
+// =============================================================================
+/** Get a string value from a PDF dictionary */
+function dictGetName(dict, key) {
+    const val = dict.get(key);
+    return typeof val === "string" ? val : undefined;
+}
+/** Get a number value from a PDF dictionary */
+function dictGetNumber(dict, key) {
+    const val = dict.get(key);
+    return typeof val === "number" ? val : undefined;
+}
+/** Get a boolean value from a PDF dictionary */
+function dictGetBool(dict, key) {
+    const val = dict.get(key);
+    return typeof val === "boolean" ? val : undefined;
+}
+/** Get a dictionary value from a PDF dictionary */
+function dictGetDict(dict, key) {
+    const val = dict.get(key);
+    return isPdfDict(val) ? val : undefined;
+}
+/** Get an array value from a PDF dictionary */
+function dictGetArray(dict, key) {
+    const val = dict.get(key);
+    return isPdfArray(val) ? val : undefined;
+}
+/** Get a ref from a PDF dictionary */
+function dictGetRef(dict, key) {
+    const val = dict.get(key);
+    return isPdfRef(val) ? val : undefined;
+}
+/** Get bytes (string as Uint8Array) from a PDF dictionary */
+function dictGetBytes(dict, key) {
+    const val = dict.get(key);
+    return val instanceof Uint8Array ? val : undefined;
+}
+/** Get a string value that may be either a name (string) or bytes decoded as latin1 */
+function dictGetString(dict, key) {
+    const val = dict.get(key);
+    if (typeof val === "string") {
+        return val;
+    }
+    if (val instanceof Uint8Array) {
+        return decodePdfStringBytes(val);
+    }
+    return undefined;
+}
+/**
+ * Decode PDF string bytes to a JavaScript string.
+ * Handles UTF-16BE (BOM = FEFF) and PDFDocEncoding (Latin-1 superset).
+ */
+function decodePdfStringBytes(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        // UTF-16BE
+        let result = "";
+        for (let i = 2; i + 1 < bytes.length; i += 2) {
+            const code = (bytes[i] << 8) | bytes[i + 1];
+            // Handle surrogate pairs
+            if (code >= 0xd800 && code <= 0xdbff && i + 3 < bytes.length) {
+                const low = (bytes[i + 2] << 8) | bytes[i + 3];
+                if (low >= 0xdc00 && low <= 0xdfff) {
+                    const cp = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+                    result += String.fromCodePoint(cp);
+                    i += 2;
+                    continue;
+                }
+            }
+            result += String.fromCharCode(code);
+        }
+        return result;
+    }
+    // UTF-8 BOM
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return new TextDecoder("utf-8").decode(bytes.subarray(3));
+    }
+    // PDFDocEncoding (identical to Latin-1 / ISO 8859-1 for 0x00-0xFF,
+    // with some differences in 0x80-0x9F range)
+    return decodePdfDocEncoding(bytes);
+}
+/** Decode bytes using PDFDocEncoding */
+function decodePdfDocEncoding(bytes) {
+    let result = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        const mapped = PDF_DOC_ENCODING[b];
+        result += mapped !== undefined ? String.fromCodePoint(mapped) : String.fromCharCode(b);
+    }
+    return result;
+}
+/**
+ * PDFDocEncoding differences from Latin-1 in the 0x80-0xAD range.
+ * @see PDF Reference 1.7, Table D.2
+ */
+const PDF_DOC_ENCODING = {
+    0x80: 0x2022, // •
+    0x81: 0x2020, // †
+    0x82: 0x2021, // ‡
+    0x83: 0x2026, // …
+    0x84: 0x2014, // —
+    0x85: 0x2013, // –
+    0x86: 0x0192, // ƒ
+    0x87: 0x2044, // ⁄
+    0x88: 0x2039, // ‹
+    0x89: 0x203a, // ›
+    0x8a: 0x2212, // −
+    0x8b: 0x2030, // ‰
+    0x8c: 0x201e, // „
+    0x8d: 0x201c, // "
+    0x8e: 0x201d, // "
+    0x8f: 0x2018, // '
+    0x90: 0x2019, // '
+    0x91: 0x201a, // ‚
+    0x92: 0x2122, // ™
+    0x93: 0xfb01, // fi
+    0x94: 0xfb02, // fl
+    0x95: 0x0141, // Ł
+    0x96: 0x0152, // Œ
+    0x97: 0x0160, // Š
+    0x98: 0x0178, // Ÿ
+    0x99: 0x017d, // Ž
+    0x9a: 0x0131, // ı
+    0x9b: 0x0142, // ł
+    0x9c: 0x0153, // œ
+    0x9d: 0x0161, // š
+    0x9e: 0x017e, // ž
+    0xa0: 0x20ac, // €
+    0xad: 0x02c7 //  ˇ
+};
+// =============================================================================
+// PDF Object Parser
+// =============================================================================
+/**
+ * Parse a single PDF object from the tokenizer.
+ *
+ * Handles all PDF object types including dictionaries (with possible streams),
+ * arrays, strings, numbers, names, booleans, null, and indirect references.
+ */
+function parseObject(tokenizer) {
+    const token = tokenizer.next();
+    return parseObjectFromToken(tokenizer, token);
+}
+/**
+ * Parse a PDF object given the first token has already been consumed.
+ */
+function parseObjectFromToken(tokenizer, token) {
+    switch (token.type) {
+        case 0 /* TokenType.Number */: {
+            // Could be: number, or start of indirect ref (N gen R) or indirect obj (N gen obj)
+            const num = token.numValue;
+            const savedPos = tokenizer.pos;
+            const next = tokenizer.next();
+            if (next.type === 0 /* TokenType.Number */) {
+                const gen = next.numValue;
+                const next2 = tokenizer.next();
+                if (next2.type === 6 /* TokenType.Keyword */ && next2.strValue === "R") {
+                    // Indirect reference: N gen R
+                    return { type: "ref", objNum: num, gen };
+                }
+                if (next2.type === 6 /* TokenType.Keyword */ && next2.strValue === "obj") {
+                    // Indirect object definition: N gen obj ... endobj
+                    const obj = parseObject(tokenizer);
+                    // Check if it's a stream
+                    if (isPdfDict(obj)) {
+                        tokenizer.skipWhitespaceAndComments();
+                        const peekPos = tokenizer.pos;
+                        const maybeStream = tokenizer.next();
+                        if (maybeStream.type === 6 /* TokenType.Keyword */ && maybeStream.strValue === "stream") {
+                            const length = dictGetNumber(obj, "Length") ?? -1;
+                            const streamData = tokenizer.readStreamContent(length);
+                            // Consume endobj
+                            const endobj = tokenizer.next();
+                            if (endobj.type !== 6 /* TokenType.Keyword */ || endobj.strValue !== "endobj") {
+                                // Some PDFs don't have endobj after endstream — tolerate
+                                tokenizer.pos = endobj.offset;
+                            }
+                            return { type: "stream", dict: obj, data: streamData };
+                        }
+                        // Not a stream — restore position
+                        tokenizer.pos = peekPos;
+                    }
+                    // Consume endobj
+                    tokenizer.skipWhitespaceAndComments();
+                    const peekEnd = tokenizer.pos;
+                    const endTok = tokenizer.next();
+                    if (endTok.type !== 6 /* TokenType.Keyword */ || endTok.strValue !== "endobj") {
+                        tokenizer.pos = peekEnd;
+                    }
+                    return obj;
+                }
+                // Not a ref or obj definition — restore
+                tokenizer.pos = savedPos;
+                return num;
+            }
+            // Not followed by another number — just a number
+            tokenizer.pos = savedPos;
+            return num;
+        }
+        case 1 /* TokenType.LiteralString */:
+        case 2 /* TokenType.HexString */:
+            return token.rawBytes ?? new Uint8Array(0);
+        case 3 /* TokenType.Name */:
+            return token.strValue;
+        case 4 /* TokenType.Boolean */:
+            return token.boolValue;
+        case 5 /* TokenType.Null */:
+            return null;
+        case 7 /* TokenType.DictBegin */:
+            return parseDictionary(tokenizer);
+        case 9 /* TokenType.ArrayBegin */:
+            return parseArray(tokenizer);
+        case 11 /* TokenType.EOF */:
+            throw new errors_1.PdfStructureError("Unexpected end of input while parsing PDF object");
+        default:
+            // Keywords like "endobj", "stream" etc. are unexpected in object context
+            // Return them as-is for the caller to handle
+            return token.strValue ?? null;
+    }
+}
+/**
+ * Parse a PDF dictionary (after the `<<` token has been consumed).
+ */
+function parseDictionary(tokenizer) {
+    const dict = new Map();
+    while (true) {
+        const keyToken = tokenizer.next();
+        if (keyToken.type === 8 /* TokenType.DictEnd */) {
+            break;
+        }
+        if (keyToken.type === 11 /* TokenType.EOF */) {
+            throw new errors_1.PdfStructureError("Unexpected EOF in dictionary");
+        }
+        if (keyToken.type !== 3 /* TokenType.Name */) {
+            // Some malformed PDFs have non-name keys — skip and try again
+            continue;
+        }
+        const key = keyToken.strValue;
+        const value = parseObject(tokenizer);
+        dict.set(key, value);
+    }
+    return dict;
+}
+/**
+ * Parse a PDF array (after the `[` token has been consumed).
+ */
+function parseArray(tokenizer) {
+    const arr = [];
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === 10 /* TokenType.ArrayEnd */) {
+            break;
+        }
+        if (token.type === 11 /* TokenType.EOF */) {
+            throw new errors_1.PdfStructureError("Unexpected EOF in array");
+        }
+        arr.push(parseObjectFromToken(tokenizer, token));
+    }
+    return arr;
+}

package/dist/cjs/modules/pdf/reader/pdf-reader.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * PDF reader — public API.
+ *
+ * Provides a high-level, zero-dependency interface for reading PDF files.
+ * Supports:
+ * - Text extraction with multilingual support (WinAnsi, MacRoman, CJK via
+ *   ToUnicode CMap, Identity-H/V, Symbol, ZapfDingbats)
+ * - Image extraction (JPEG, JPEG2000, raw/Flate, CCITT, JBIG2)
+ * - Annotation extraction (links, comments, highlights, stamps, etc.)
+ * - Form field extraction (AcroForm: text inputs, checkboxes, radio buttons, dropdowns)
+ * - Metadata reading (Info dictionary + XMP)
+ * - Encrypted PDFs:
+ *   - RC4 (40-bit and 128-bit) — tested via roundtrip
+ *   - AES-128 (V=4, R=4) — implemented, requires external test fixtures
+ *   - AES-256 (V=5, R=5) — implemented, requires external test fixtures
+ * - Cross-reference tables and streams (PDF 1.5+)
+ * - Incremental updates and xref recovery
+ *
+ * @example Basic text extraction:
+ * ```typescript
+ * import { readPdf } from "excelts/pdf";
+ *
+ * const pdf = readPdf(pdfBytes);
+ * console.log(pdf.text);           // All text from all pages
+ * console.log(pdf.pages[0].text);  // Text from page 1
+ * ```
+ *
+ * @example Image extraction:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes);
+ * for (const image of pdf.pages[0].images) {
+ *   console.log(image.format, image.width, image.height);
+ *   fs.writeFileSync(`image.${image.format}`, image.data);
+ * }
+ * ```
+ *
+ * @example Metadata:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes);
+ * console.log(pdf.metadata.title);
+ * console.log(pdf.metadata.author);
+ * console.log(pdf.metadata.pageCount);
+ * ```
+ *
+ * @example Encrypted PDF:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes, { password: "secret" });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPdf = readPdf;
+const pdf_document_1 = require("./pdf-document");
+const pdf_decrypt_1 = require("./pdf-decrypt");
+const content_interpreter_1 = require("./content-interpreter");
+const text_reconstruction_1 = require("./text-reconstruction");
+const image_extractor_1 = require("./image-extractor");
+const annotation_extractor_1 = require("./annotation-extractor");
+const form_extractor_1 = require("./form-extractor");
+const metadata_reader_1 = require("./metadata-reader");
+const errors_1 = require("../errors");
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Read a PDF file and extract text, images, and metadata.
+ *
+ * @param data - Raw PDF file bytes
+ * @param options - Extraction options
+ * @returns Extracted content
+ * @throws {PdfStructureError} If the PDF structure is invalid
+ * @throws {PdfError} If decryption fails (wrong password)
+ */
+function readPdf(data, options) {
+    const opts = {
+        password: options?.password ?? "",
+        pages: options?.pages,
+        extractText: options?.extractText ?? true,
+        extractImages: options?.extractImages ?? true,
+        extractMetadata: options?.extractMetadata ?? true,
+        extractAnnotations: options?.extractAnnotations ?? true,
+        extractFormFields: options?.extractFormFields ?? true
+    };
+    // Parse document structure
+    const doc = new pdf_document_1.PdfDocument(data);
+    // Handle encryption
+    if ((0, pdf_decrypt_1.isEncrypted)(doc)) {
+        const success = (0, pdf_decrypt_1.initDecryption)(doc, opts.password);
+        if (!success) {
+            throw new errors_1.PdfStructureError("Failed to decrypt PDF: incorrect password");
+        }
+    }
+    // Extract metadata
+    const metadata = opts.extractMetadata ? (0, metadata_reader_1.extractMetadata)(doc) : createEmptyMetadata();
+    // Get pages (with object identity for correct decryption)
+    const pagesInfo = doc.getPagesWithObjInfo();
+    const pageIndicesToProcess = opts.pages
+        ? opts.pages.map(p => p - 1).filter(p => p >= 0 && p < pagesInfo.length)
+        : Array.from({ length: pagesInfo.length }, (_, i) => i);
+    // Process each page
+    const pages = [];
+    for (const pageIdx of pageIndicesToProcess) {
+        const { dict: pageDict } = pagesInfo[pageIdx];
+        const pageNumber = pageIdx + 1;
+        const warnings = [];
+        // Extract text
+        let text = "";
+        let textLines = [];
+        let textFragments = [];
+        if (opts.extractText) {
+            try {
+                textFragments = (0, content_interpreter_1.extractTextFromPage)(pageDict, doc);
+                text = (0, text_reconstruction_1.reconstructText)(textFragments);
+                textLines = (0, text_reconstruction_1.reconstructTextLines)(textFragments);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Text extraction failed on page ${pageNumber}: ${msg}`);
+            }
+        }
+        // Extract images
+        let images = [];
+        if (opts.extractImages) {
+            try {
+                images = (0, image_extractor_1.extractImagesFromPage)(pageDict, doc);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Image extraction failed on page ${pageNumber}: ${msg}`);
+            }
+        }
+        // Extract annotations
+        let annotations = [];
+        if (opts.extractAnnotations) {
+            try {
+                annotations = (0, annotation_extractor_1.extractAnnotationsFromPage)(pageDict, doc);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Annotation extraction failed on page ${pageNumber}: ${msg}`);
+            }
+        }
+        // Get page dimensions
+        const { width, height } = getPageDimensions(pageDict, doc);
+        pages.push({
+            pageNumber,
+            text,
+            textLines,
+            textFragments,
+            images,
+            annotations,
+            width,
+            height,
+            warnings
+        });
+    }
+    // Concatenate all page text
+    const allText = pages.map(p => p.text).join("\n\n");
+    // Update page count in metadata
+    if (opts.extractMetadata) {
+        metadata.pageCount = pagesInfo.length;
+    }
+    // Extract form fields (document-level, not per-page)
+    let formFields = [];
+    if (opts.extractFormFields) {
+        try {
+            formFields = (0, form_extractor_1.extractFormFields)(doc);
+        }
+        catch {
+            // Non-fatal — just return empty
+        }
+    }
+    return {
+        text: allText,
+        pages,
+        metadata,
+        formFields
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function getPageDimensions(pageDict, doc) {
+    return doc.resolvePageBox(pageDict) ?? { width: 612, height: 792 }; // Default: US Letter
+}
+function createEmptyMetadata() {
+    return {
+        title: "",
+        author: "",
+        subject: "",
+        keywords: "",
+        creator: "",
+        producer: "",
+        creationDate: null,
+        modDate: null,
+        pdfVersion: "",
+        pageCount: 0,
+        encrypted: false,
+        pageSize: null,
+        xmpXml: null,
+        custom: {}
+    };
+}