@cj-tech-master/excelts 8.0.0 → 8.1.0

package/dist/types/modules/pdf/reader/pdf-document.d.ts

@@ -0,0 +1,191 @@
+/**
+ * PDF document parser.
+ *
+ * Handles the high-level PDF file structure:
+ * - Locating startxref
+ * - Parsing cross-reference tables (traditional and stream-based)
+ * - Reading trailer dictionaries
+ * - Resolving indirect object references
+ * - Handling incremental updates
+ *
+ * @see PDF Reference 1.7, §3.4 - File Structure
+ */
+import type { PdfObject, PdfDictValue, PdfRef, PdfStream } from "./pdf-parser.js";
+/** Result of resolving an object with its object/generation numbers for decryption */
+interface ResolvedObject {
+    /** The resolved PDF object */
+    obj: PdfObject | null;
+    /** The object number */
+    objNum: number;
+    /** The generation number */
+    gen: number;
+}
+/**
+ * Parsed PDF document with lazy object resolution.
+ *
+ * Reads the cross-reference table and trailer on construction,
+ * then resolves individual objects on demand with caching.
+ */
+export declare class PdfDocument {
+    private tokenizer;
+    private xref;
+    private cache;
+    readonly trailer: PdfDictValue;
+    /** Encryption handler (set externally after decryption is initialized) */
+    decryptFn: ((data: Uint8Array, objNum: number, gen: number) => Uint8Array) | null;
+    constructor(data: Uint8Array);
+    /** Get the underlying raw data */
+    get data(): Uint8Array;
+    private parseFileStructure;
+    /**
+     * Find the startxref offset by scanning backward from EOF.
+     */
+    private findStartxref;
+    /**
+     * Parse the xref chain starting at the given offset.
+     * Follows /Prev links for incremental updates.
+     * Returns the merged trailer dictionary.
+     */
+    private parseXrefChain;
+    /**
+     * Parse a traditional xref table and its trailer.
+     */
+    private parseTraditionalXref;
+    /**
+     * Parse a cross-reference stream (PDF 1.5+).
+     */
+    private parseXrefStream;
+    /**
+     * Reconstruct the xref table by scanning the entire file for `N N obj` patterns.
+     * This is a fallback for corrupted or broken PDFs where the normal xref parsing fails.
+     *
+     * @returns A synthetic trailer dictionary
+     */
+    private reconstructXref;
+    /**
+     * Merge trailer entries from an older trailer into the current one.
+     * Only adds keys that don't already exist.
+     */
+    private mergeTrailer;
+    /**
+     * Resolve a PDF object by its object number and generation.
+     * Returns null if the object doesn't exist.
+     */
+    resolve(objNum: number, gen?: number): PdfObject | null;
+    /**
+     * Resolve a PDF object and return it along with its object/generation numbers.
+     * Useful for tracking which object a value came from (for decryption).
+     *
+     * @param objNum - The object number to resolve
+     * @param gen - The generation number (default 0)
+     * @returns The resolved object with its objNum and gen for decryption context
+     */
+    resolveWithObjNum(objNum: number, gen?: number): ResolvedObject;
+    /**
+     * Dereference a PdfRef to its actual object value.
+     * If the input is not a PdfRef, returns it as-is.
+     */
+    deref(obj: PdfObject | null | undefined): PdfObject | null;
+    /**
+     * Dereference a PdfRef and assert it's a dictionary.
+     */
+    derefDict(obj: PdfObject | null | undefined): PdfDictValue | null;
+    /**
+     * Dereference a PdfRef and get the stream, along with the objNum/gen
+     * needed for correct per-object decryption.
+     */
+    derefStream(obj: PdfObject | null | undefined): PdfStream | null;
+    /**
+     * Dereference a PdfRef and get the stream with its object number and generation.
+     * Returns null if the object is not a stream.
+     * The objNum/gen are needed for correct per-object decryption (V1-V4).
+     */
+    derefStreamWithObjNum(obj: PdfObject | null | undefined): {
+        stream: PdfStream;
+        objNum: number;
+        gen: number;
+    } | null;
+    /**
+     * Get decoded stream data from a stream object.
+     * Applies filter chain decoding and decryption.
+     *
+     * When objNum/gen are not provided (default 0), decryption may not
+     * produce correct results. Use {@link resolveWithObjNum} to obtain
+     * the correct objNum/gen for the stream's containing object.
+     */
+    getStreamData(stream: PdfStream, objNum?: number, gen?: number): Uint8Array;
+    /**
+     * Decrypt a string value (bytes) if encryption is active.
+     */
+    decryptString(bytes: Uint8Array, objNum: number, gen: number): Uint8Array;
+    /**
+     * Decode a PDF string to a JS string, with optional decryption.
+     */
+    decodeString(bytes: Uint8Array, objNum?: number, gen?: number): string;
+    /**
+     * Recursively decrypt all string values (Uint8Array) within a parsed PDF object.
+     * PDF spec requires all strings in an encrypted document to be decrypted using
+     * the per-object key derived from the containing object's objNum/gen.
+     * Streams are NOT decrypted here — they are decrypted in getStreamData().
+     */
+    private decryptObjectStrings;
+    /**
+     * Get the catalog dictionary (the root of the document structure).
+     */
+    getCatalog(): PdfDictValue;
+    /**
+     * Get the pages array from the page tree.
+     * Returns an array of page dictionaries in order.
+     */
+    getPages(): PdfDictValue[];
+    /**
+     * Get pages with their object numbers (needed for correct decryption of
+     * inline streams within page objects).
+     */
+    getPagesWithObjInfo(): Array<{
+        dict: PdfDictValue;
+        objNum: number;
+        gen: number;
+    }>;
+    /**
+     * Recursively collect page dictionaries from the page tree.
+     * Uses a visited set to prevent infinite recursion on cyclic page trees.
+     */
+    private collectPages;
+    /**
+     * Get the object number for a given object reference.
+     * Useful for tracking which object a value came from (for decryption).
+     */
+    getObjNumForRef(ref: PdfRef): number;
+    /**
+     * Parse an object definition at the given byte offset.
+     */
+    private parseObjectAt;
+    /**
+     * Parse a compressed object from an object stream.
+     * @param objStmNum - The object number of the object stream
+     * @param index - The index of the object within the stream
+     */
+    private parseCompressedObject;
+    /**
+     * Parse all objects from an object stream.
+     * @returns Map of object number → object value
+     */
+    private parseObjectStream;
+    /**
+     * Resolve a page's bounding box (MediaBox/CropBox) with indirect ref resolution
+     * and parent inheritance. Returns `{ width, height }` or null if no box found.
+     *
+     * This is a shared helper so callers don't duplicate box resolution logic.
+     */
+    resolvePageBox(pageDict: PdfDictValue, visited?: Set<PdfDictValue>): {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * Resolve a page's Resources dictionary, inheriting from parent pages if needed.
+     * Protected against cyclic parent chains.
+     */
+    resolvePageResources(pageDict: PdfDictValue, visited?: Set<PdfDictValue>): PdfDictValue;
+}
+export {};

package/dist/types/modules/pdf/reader/pdf-parser.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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
+ */
+import type { Token, PdfTokenizer } from "./pdf-tokenizer.js";
+/** A PDF indirect object reference: `N gen R` */
+export interface PdfRef {
+    readonly type: "ref";
+    readonly objNum: number;
+    readonly gen: number;
+}
+/** A PDF stream: dictionary + raw data bytes */
+export interface PdfStream {
+    readonly type: "stream";
+    readonly dict: PdfDictValue;
+    readonly data: Uint8Array;
+}
+/** A PDF dictionary: key-value pairs where keys are names */
+export type PdfDictValue = Map<string, PdfObject>;
+/** A PDF array */
+export type PdfArrayValue = PdfObject[];
+/**
+ * Union type for all possible PDF object values.
+ */
+export type PdfObject = number | string | boolean | null | Uint8Array | PdfRef | PdfDictValue | PdfArrayValue | PdfStream;
+export declare function isPdfRef(obj: PdfObject | undefined): obj is PdfRef;
+export declare function isPdfStream(obj: PdfObject | undefined): obj is PdfStream;
+export declare function isPdfDict(obj: PdfObject | undefined): obj is PdfDictValue;
+export declare function isPdfArray(obj: PdfObject | undefined): obj is PdfArrayValue;
+/** Get a string value from a PDF dictionary */
+export declare function dictGetName(dict: PdfDictValue, key: string): string | undefined;
+/** Get a number value from a PDF dictionary */
+export declare function dictGetNumber(dict: PdfDictValue, key: string): number | undefined;
+/** Get a boolean value from a PDF dictionary */
+export declare function dictGetBool(dict: PdfDictValue, key: string): boolean | undefined;
+/** Get a dictionary value from a PDF dictionary */
+export declare function dictGetDict(dict: PdfDictValue, key: string): PdfDictValue | undefined;
+/** Get an array value from a PDF dictionary */
+export declare function dictGetArray(dict: PdfDictValue, key: string): PdfArrayValue | undefined;
+/** Get a ref from a PDF dictionary */
+export declare function dictGetRef(dict: PdfDictValue, key: string): PdfRef | undefined;
+/** Get bytes (string as Uint8Array) from a PDF dictionary */
+export declare function dictGetBytes(dict: PdfDictValue, key: string): Uint8Array | undefined;
+/** Get a string value that may be either a name (string) or bytes decoded as latin1 */
+export declare function dictGetString(dict: PdfDictValue, key: string): string | undefined;
+/**
+ * Decode PDF string bytes to a JavaScript string.
+ * Handles UTF-16BE (BOM = FEFF) and PDFDocEncoding (Latin-1 superset).
+ */
+export declare function decodePdfStringBytes(bytes: Uint8Array): string;
+/**
+ * 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.
+ */
+export declare function parseObject(tokenizer: PdfTokenizer): PdfObject;
+/**
+ * Parse a PDF object given the first token has already been consumed.
+ */
+export declare function parseObjectFromToken(tokenizer: PdfTokenizer, token: Token): PdfObject;

package/dist/types/modules/pdf/reader/pdf-reader.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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" });
+ * ```
+ */
+import type { TextLine } from "./text-reconstruction.js";
+import type { TextFragment } from "./content-interpreter.js";
+import type { ExtractedImage } from "./image-extractor.js";
+import type { PdfAnnotation } from "./annotation-extractor.js";
+import type { PdfFormField } from "./form-extractor.js";
+import type { PdfMetadata } from "./metadata-reader.js";
+/**
+ * Options for reading a PDF.
+ */
+export interface ReadPdfOptions {
+    /**
+     * Password for encrypted PDFs.
+     * Can be either the user password or owner password.
+     * @default ""
+     */
+    password?: string;
+    /**
+     * Which pages to extract (1-based).
+     * If omitted, all pages are extracted.
+     * @example [1, 3, 5] — extract pages 1, 3, and 5
+     */
+    pages?: number[];
+    /**
+     * Whether to extract text.
+     * @default true
+     */
+    extractText?: boolean;
+    /**
+     * Whether to extract images.
+     * @default true
+     */
+    extractImages?: boolean;
+    /**
+     * Whether to extract metadata.
+     * @default true
+     */
+    extractMetadata?: boolean;
+    /**
+     * Whether to extract annotations (links, comments, highlights, etc.).
+     * @default true
+     */
+    extractAnnotations?: boolean;
+    /**
+     * Whether to extract form fields (AcroForm: text inputs, checkboxes, dropdowns, etc.).
+     * @default true
+     */
+    extractFormFields?: boolean;
+}
+/**
+ * A single page from a read PDF.
+ */
+export interface ReadPdfPage {
+    /** 1-based page number */
+    pageNumber: number;
+    /** Extracted text content */
+    text: string;
+    /** Structured text lines with position information */
+    textLines: TextLine[];
+    /** Raw text fragments with exact positions */
+    textFragments: TextFragment[];
+    /** Extracted images */
+    images: ExtractedImage[];
+    /** Extracted annotations (links, comments, highlights, etc.) */
+    annotations: PdfAnnotation[];
+    /** Page width in points */
+    width: number;
+    /** Page height in points */
+    height: number;
+    /** Warnings encountered during extraction (non-fatal errors) */
+    warnings: string[];
+}
+/**
+ * Result of reading a PDF.
+ */
+export interface ReadPdfResult {
+    /** All text from all pages concatenated */
+    text: string;
+    /** Per-page results */
+    pages: ReadPdfPage[];
+    /** Document metadata */
+    metadata: PdfMetadata;
+    /** Form fields extracted from AcroForm (document-level) */
+    formFields: PdfFormField[];
+}
+/**
+ * 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)
+ */
+export declare function readPdf(data: Uint8Array, options?: ReadPdfOptions): ReadPdfResult;

package/dist/types/modules/pdf/reader/pdf-tokenizer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * PDF tokenizer / lexer.
+ *
+ * Scans raw PDF bytes and produces a stream of typed tokens.
+ * Handles all PDF token types: numbers, strings (literal and hex),
+ * names, booleans, null, keywords, and delimiters.
+ *
+ * @see PDF Reference 1.7, §3.1 - Lexical Conventions
+ */
+export declare const enum TokenType {
+    /** Integer or real number */
+    Number = 0,
+    /** Literal string delimited by parentheses `(...)` */
+    LiteralString = 1,
+    /** Hex string delimited by angle brackets `<...>` */
+    HexString = 2,
+    /** Name object starting with `/` */
+    Name = 3,
+    /** Boolean `true` or `false` */
+    Boolean = 4,
+    /** The `null` keyword */
+    Null = 5,
+    /** Keywords: obj, endobj, stream, endstream, xref, trailer, startxref, R */
+    Keyword = 6,
+    /** `<<` dict begin */
+    DictBegin = 7,
+    /** `>>` dict end */
+    DictEnd = 8,
+    /** `[` array begin */
+    ArrayBegin = 9,
+    /** `]` array end */
+    ArrayEnd = 10,
+    /** End of input */
+    EOF = 11
+}
+export interface Token {
+    type: TokenType;
+    /** Numeric value (for Number tokens) */
+    numValue?: number;
+    /** String value (for String, Name, Keyword, Boolean tokens) */
+    strValue?: string;
+    /** Raw bytes (for LiteralString and HexString tokens) */
+    rawBytes?: Uint8Array;
+    /** Boolean value (for Boolean tokens) */
+    boolValue?: boolean;
+    /** Byte offset where this token starts */
+    offset: number;
+}
+/**
+ * Byte-level PDF tokenizer.
+ *
+ * Provides a `next()` method that returns the next token from the input.
+ * The tokenizer maintains a mutable position pointer that advances through
+ * the input bytes.
+ */
+export declare class PdfTokenizer {
+    private data;
+    pos: number;
+    constructor(data: Uint8Array, offset?: number);
+    /** Get current position */
+    get position(): number;
+    /** Set current position */
+    set position(offset: number);
+    /** Get the underlying data */
+    get bytes(): Uint8Array;
+    /** Peek at the byte at the current position without consuming it */
+    peek(): number;
+    /** Read the next token */
+    next(): Token;
+    skipWhitespaceAndComments(): void;
+    private readLiteralString;
+    private readHexString;
+    private readName;
+    private readNumber;
+    private readKeyword;
+    /**
+     * Search forward for a byte sequence starting from the current position.
+     * Returns the offset where the sequence starts, or -1 if not found.
+     * Does NOT advance the position.
+     */
+    findSequence(seq: Uint8Array, from?: number): number;
+    /**
+     * Search backward for a byte sequence starting from `from` (or end of data).
+     * Returns the offset where the sequence starts, or -1 if not found.
+     */
+    findSequenceBackward(seq: Uint8Array, from?: number): number;
+    /**
+     * Read a line of text at the current position. Advances past the line ending.
+     */
+    readLine(): string;
+    /**
+     * Extract a slice of the underlying data.
+     */
+    slice(start: number, end: number): Uint8Array;
+    /**
+     * Read the stream content following a `stream` keyword.
+     * The tokenizer should be positioned right after the `stream` keyword.
+     * Returns the raw stream bytes (between stream\n and endstream).
+     */
+    readStreamContent(length: number): Uint8Array;
+}

package/dist/types/modules/pdf/reader/reader-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared utility functions for PDF reader modules.
+ */
+import type { PdfDocument } from "./pdf-document.js";
+import type { PdfDictValue } from "./pdf-parser.js";
+/**
+ * Safely extract a string value from a PDF dictionary entry.
+ * Handles both name strings and Uint8Array PDF strings (with BOM/encoding detection).
+ *
+ * @param dict - The PDF dictionary
+ * @param key - The key to look up
+ * @param doc - The PDF document for resolving indirect references
+ * @returns The string value, or empty string if not found or not a string
+ */
+export declare function getDictStringValue(dict: PdfDictValue, key: string, doc: PdfDocument): string;

package/dist/types/modules/pdf/reader/stream-filters.d.ts

@@ -0,0 +1,20 @@
+/**
+ * PDF stream filter decoder chain.
+ *
+ * Decodes PDF stream data by applying the appropriate filter(s)
+ * specified in the stream dictionary's /Filter entry.
+ *
+ * Supported filters:
+ * - /FlateDecode (zlib/deflate compression)
+ * - /ASCII85Decode (ASCII base-85 encoding)
+ * - /ASCIIHexDecode (ASCII hexadecimal encoding)
+ * - /LZWDecode (LZW compression)
+ * - /RunLengthDecode (run-length encoding)
+ *
+ * @see PDF Reference 1.7, §3.3 - Filters
+ */
+import type { PdfDictValue } from "./pdf-parser.js";
+/**
+ * Decode stream data by applying the filter chain from the stream dictionary.
+ */
+export declare function decodeStreamFilters(data: Uint8Array, dict: PdfDictValue): Uint8Array;

package/dist/types/modules/pdf/reader/text-reconstruction.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Text reconstruction from positioned text fragments.
+ *
+ * Assembles raw text fragments extracted from PDF content streams into
+ * coherent, human-readable text with proper reading order, line breaks,
+ * and paragraph detection.
+ *
+ * Challenges addressed:
+ * - PDF text has no semantic structure (only "draw char at (x,y)")
+ * - Text fragments may be out of order
+ * - Word and line boundaries must be inferred from positions
+ * - Columns and tables need proper handling
+ * - Different fonts/sizes affect spacing thresholds
+ * - Multi-column layouts need column detection
+ * - RTL (Arabic, Hebrew) text needs right-to-left sorting
+ * - Vertical CJK text needs column-based grouping
+ *
+ * @see PDF Reference 1.7, Chapter 5 - Text
+ */
+import type { TextFragment } from "./content-interpreter.js";
+/**
+ * Reconstruct readable text from positioned text fragments.
+ *
+ * @param fragments - Raw text fragments with positions from content stream
+ * @returns Reconstructed text with proper line breaks and spacing
+ */
+export declare function reconstructText(fragments: TextFragment[]): string;
+/**
+ * Detailed text extraction result preserving position information.
+ */
+export interface TextLine {
+    /** The text content of this line */
+    text: string;
+    /** Y position (PDF coordinate, origin = bottom-left) */
+    y: number;
+    /** X position of the start of the line */
+    x: number;
+    /** Font size of the first fragment */
+    fontSize: number;
+}
+/**
+ * Extract text as structured lines.
+ */
+export declare function reconstructTextLines(fragments: TextFragment[]): TextLine[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.",
   "type": "module",
   "main": "./dist/cjs/index.js",