@cj-tech-master/excelts 8.1.2 → 9.0.0

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

@@ -16,18 +16,18 @@
  * - Cross-reference tables and streams (PDF 1.5+)
  * - Incremental updates and xref recovery
  *
- * @example Basic text extraction:
+ * @example Text extraction:
  * ```typescript
  * import { readPdf } from "excelts/pdf";
  *
- * const pdf = readPdf(pdfBytes);
+ * const pdf = await 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);
+ * const pdf = await 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);
@@ -36,7 +36,7 @@
  *
  * @example Metadata:
  * ```typescript
- * const pdf = readPdf(pdfBytes);
+ * const pdf = await readPdf(pdfBytes);
  * console.log(pdf.metadata.title);
  * console.log(pdf.metadata.author);
  * console.log(pdf.metadata.pageCount);
@@ -44,7 +44,7 @@
  *
  * @example Encrypted PDF:
  * ```typescript
- * const pdf = readPdf(pdfBytes, { password: "secret" });
+ * const pdf = await readPdf(pdfBytes, { password: "secret" });
  * ```
  */
 import { PdfDocument } from "./pdf-document.js";
@@ -56,19 +56,36 @@ import { extractAnnotationsFromPage } from "./annotation-extractor.js";
 import { extractFormFields } from "./form-extractor.js";
 import { extractMetadata } from "./metadata-reader.js";
 import { PdfStructureError } from "../errors.js";
+import { yieldToEventLoop } from "../../../utils/utils.base.js";
 // =============================================================================
 // Public API
 // =============================================================================
 /**
  * Read a PDF file and extract text, images, and metadata.
+ * Yields to the event loop between pages to avoid blocking.
  *
  * @param data - Raw PDF file bytes
  * @param options - Extraction options
- * @returns Extracted content
+ * @returns Promise of extracted content
  * @throws {PdfStructureError} If the PDF structure is invalid
  * @throws {PdfError} If decryption fails (wrong password)
  */
-export function readPdf(data, options) {
+export async function readPdf(data, options) {
+    const { doc, opts, metadata, pagesInfo, pageIndicesToProcess } = prepareRead(data, options);
+    const pages = [];
+    for (let i = 0; i < pageIndicesToProcess.length; i++) {
+        const pageIdx = pageIndicesToProcess[i];
+        pages.push(processPage(pagesInfo[pageIdx].dict, pageIdx, doc, opts));
+        if (i < pageIndicesToProcess.length - 1) {
+            await yieldToEventLoop();
+        }
+    }
+    return finalizeRead(pages, pagesInfo.length, metadata, opts, doc);
+}
+/**
+ * Shared setup: parse document, handle encryption, extract metadata, resolve pages.
+ */
+function prepareRead(data, options) {
     const opts = {
         password: options?.password ?? "",
         pages: options?.pages,
@@ -78,86 +95,81 @@ export function readPdf(data, options) {
         extractAnnotations: options?.extractAnnotations ?? true,
         extractFormFields: options?.extractFormFields ?? true
     };
-    // Parse document structure
     const doc = new PdfDocument(data);
-    // Handle encryption
     if (isEncrypted(doc)) {
         const success = initDecryption(doc, opts.password);
         if (!success) {
             throw new PdfStructureError("Failed to decrypt PDF: incorrect password");
         }
     }
-    // Extract metadata
     const metadata = opts.extractMetadata ? 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 = extractTextFromPage(pageDict, doc);
-                text = reconstructText(textFragments);
-                textLines = reconstructTextLines(textFragments);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                warnings.push(`Text extraction failed on page ${pageNumber}: ${msg}`);
-            }
+    return { doc, opts, metadata, pagesInfo, pageIndicesToProcess };
+}
+/**
+ * Process a single page: extract text, images, annotations, and dimensions.
+ */
+function processPage(pageDict, pageIdx, doc, opts) {
+    const pageNumber = pageIdx + 1;
+    const warnings = [];
+    let text = "";
+    let textLines = [];
+    let textFragments = [];
+    if (opts.extractText) {
+        try {
+            textFragments = extractTextFromPage(pageDict, doc);
+            text = reconstructText(textFragments);
+            textLines = reconstructTextLines(textFragments);
         }
-        // Extract images
-        let images = [];
-        if (opts.extractImages) {
-            try {
-                images = extractImagesFromPage(pageDict, doc);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                warnings.push(`Image extraction failed on page ${pageNumber}: ${msg}`);
-            }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`Text extraction failed on page ${pageNumber}: ${msg}`);
         }
-        // Extract annotations
-        let annotations = [];
-        if (opts.extractAnnotations) {
-            try {
-                annotations = extractAnnotationsFromPage(pageDict, doc);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                warnings.push(`Annotation extraction failed on page ${pageNumber}: ${msg}`);
-            }
+    }
+    let images = [];
+    if (opts.extractImages) {
+        try {
+            images = extractImagesFromPage(pageDict, doc);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`Image extraction failed on page ${pageNumber}: ${msg}`);
+        }
+    }
+    let annotations = [];
+    if (opts.extractAnnotations) {
+        try {
+            annotations = 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 { width, height } = getPageDimensions(pageDict, doc);
+    return {
+        pageNumber,
+        text,
+        textLines,
+        textFragments,
+        images,
+        annotations,
+        width,
+        height,
+        warnings
+    };
+}
+/**
+ * Finalize: concatenate text, update metadata page count, extract form fields.
+ */
+function finalizeRead(pages, totalPageCount, metadata, opts, doc) {
     const allText = pages.map(p => p.text).join("\n\n");
-    // Update page count in metadata
     if (opts.extractMetadata) {
-        metadata.pageCount = pagesInfo.length;
+        metadata.pageCount = totalPageCount;
     }
-    // Extract form fields (document-level, not per-page)
     let formFields = [];
     if (opts.extractFormFields) {
         try {
@@ -167,12 +179,7 @@ export function readPdf(data, options) {
             // Non-fatal — just return empty
         }
     }
-    return {
-        text: allText,
-        pages,
-        metadata,
-        formFields
-    };
+    return { text: allText, pages, metadata, formFields };
 }
 // =============================================================================
 // Helpers

package/dist/browser/modules/pdf/render/constants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared rendering constants used by both the layout engine and page renderer.
+ *
+ * Keeping these in one place ensures row-height computation and text rendering
+ * use exactly the same values, preventing clipped or overlapping content.
+ */
+/** Horizontal cell padding in points (left + right = 2 × CELL_PADDING_H). */
+export declare const CELL_PADDING_H = 3;
+/** Vertical cell padding in points (top + bottom = 2 × CELL_PADDING_V). */
+export declare const CELL_PADDING_V = 2;
+/**
+ * Line-height multiplier applied to the font size.
+ *
+ * Excel's default row height for an 11pt font is 15pt, which after removing
+ * vertical padding (2 × 2 = 4pt) leaves 11pt × 1.0 — but Excel also adds
+ * internal leading. A factor of 1.2 matches standard PDF/typographic practice
+ * and keeps text readable without inflating row heights.
+ */
+export declare const LINE_HEIGHT_FACTOR = 1.2;
+/** Width of one indent level in points (~3 characters at 11pt). */
+export declare const INDENT_WIDTH = 10;
+/**
+ * Excel column widths are measured in characters of the default font's digit width.
+ * For Calibri 11pt (the default), maxDigitWidth ≈ 7 pixels at 96 DPI.
+ * Excel adds 5 pixels of padding per column (4px text margin + 1px gridline).
+ * To convert to PDF points: (charWidth × 7 + 5) × (72/96).
+ */
+export declare const MAX_DIGIT_WIDTH_PX = 7;
+export declare const EXCEL_COLUMN_PADDING_PX = 5;
+export declare const PX_TO_PT: number;

package/dist/browser/modules/pdf/render/constants.js

@@ -0,0 +1,30 @@
+/**
+ * Shared rendering constants used by both the layout engine and page renderer.
+ *
+ * Keeping these in one place ensures row-height computation and text rendering
+ * use exactly the same values, preventing clipped or overlapping content.
+ */
+/** Horizontal cell padding in points (left + right = 2 × CELL_PADDING_H). */
+export const CELL_PADDING_H = 3;
+/** Vertical cell padding in points (top + bottom = 2 × CELL_PADDING_V). */
+export const CELL_PADDING_V = 2;
+/**
+ * Line-height multiplier applied to the font size.
+ *
+ * Excel's default row height for an 11pt font is 15pt, which after removing
+ * vertical padding (2 × 2 = 4pt) leaves 11pt × 1.0 — but Excel also adds
+ * internal leading. A factor of 1.2 matches standard PDF/typographic practice
+ * and keeps text readable without inflating row heights.
+ */
+export const LINE_HEIGHT_FACTOR = 1.2;
+/** Width of one indent level in points (~3 characters at 11pt). */
+export const INDENT_WIDTH = 10;
+/**
+ * Excel column widths are measured in characters of the default font's digit width.
+ * For Calibri 11pt (the default), maxDigitWidth ≈ 7 pixels at 96 DPI.
+ * Excel adds 5 pixels of padding per column (4px text margin + 1px gridline).
+ * To convert to PDF points: (charWidth × 7 + 5) × (72/96).
+ */
+export const MAX_DIGIT_WIDTH_PX = 7;
+export const EXCEL_COLUMN_PADDING_PX = 5;
+export const PX_TO_PT = 72 / 96; // 0.75

package/dist/browser/modules/pdf/render/layout-engine.d.ts

@@ -20,6 +20,7 @@ import type { PdfSheetData, ResolvedPdfOptions, LayoutPage } from "../types.js";
 import type { FontManager } from "../font/font-manager.js";
 /**
  * Compute the layout for a sheet across one or more PDF pages.
+ * Yields to the event loop between each output page.
  */
-export declare function layoutSheet(sheet: PdfSheetData, options: ResolvedPdfOptions, fontManager: FontManager): LayoutPage[];
+export declare function layoutSheet(sheet: PdfSheetData, options: ResolvedPdfOptions, fontManager: FontManager): Promise<LayoutPage[]>;
 export declare function paginateRows(rowHeights: number[], availableHeight: number, repeatRowCount: number, rowBreaks: Set<number>): number[][];