@syncfusion/ej2-pdf/src/pdf/core/pdf-cross-reference.d.ts

Feature-rich JavaScript PDF library with built-in support for loading and manipulating PDF document.

import { _PdfStream } from './base-stream';
import { _PdfDictionary, _PdfReferenceSet, _PdfReference, _PdfCommand } from './pdf-primitives';
import { _PdfParser } from './pdf-parser';
import { _PdfBaseStream } from './base-stream';
import { PdfDocument } from './pdf-document';
import { _PdfEncryptor } from './security/encryptor';
import { _PdfSignatureDictionary } from './security/digital-signature/signature/signature-dictionary';
import { PdfSignature } from './security/digital-signature/signature/pdf-signature';
import { _CipherTransform } from './security/encryptors/cipher-tranform';
/**
 * Manages PDF cross-reference tables and streams, object lookup, and saving operations.
 *
 * @private
 */
export declare class _PdfCrossReference {
    /**
     * Chunks of output bytes used during saving.
     *
     * @private
     */
    _uint8Chunks: Array<Uint8Array>;
    /**
     * Underlying PDF stream for reading/writing objects.
     *
     * @private
     */
    _stream: _PdfStream;
    /**
     * Pending references used to detect circular references during fetch.
     *
     * @private
     */
    _pendingRefs: _PdfReferenceSet;
    /**
     * Array of object information entries representing the XRef table or stream.
     *
     * @private
     */
    _entries: _PdfObjectInformation[];
    /**
     * Map of known cross-reference positions.
     *
     * @private
     */
    _crossReferencePosition: any;
    /**
     * Cache map of indirect references to parsed objects.
     *
     * @private
     */
    _cacheMap: Map<_PdfReference, any>;
    /**
     * Queue of startxref positions to parse.
     *
     * @private
     */
    _startXRefQueue: number[];
    /**
     * Trailer dictionary parsed from the PDF.
     *
     * @private
     */
    _trailer: _PdfDictionary;
    /**
     * Root (catalog) dictionary of the PDF.
     *
     * @private
     */
    _root: _PdfDictionary;
    /**
     * Top dictionary discovered while reading XRef structures.
     *
     * @private
     */
    _topDictionary: _PdfDictionary;
    /**
     * State used while parsing an XRef table.
     *
     * @private
     */
    _tableState: _PdfCrossTableState;
    /**
     * State used while parsing an XRef stream.
     *
     * @private
     */
    _streamState: _PdfStreamState;
    /**
     * Previous startxref offset.
     *
     * @private
     */
    _prevStartXref: number;
    /**
     * PDF version string written on save.
     *
     * @private
     */
    _version: string;
    /**
     * Next object reference number to assign when saving.
     *
     * @private
     */
    _nextReferenceNumber: number;
    /**
     * Line separator used in output.
     *
     * @private
     */
    _newLine: string;
    /**
     * Owning document.
     *
     * @private
     */
    _document: PdfDocument;
    /**
     * Whether catalog updates are allowed during save.
     *
     * @private
     */
    _allowCatalog: boolean;
    /**
     * Password provided for encrypted documents.
     *
     * @private
     */
    _password: string;
    /**
     * Encryptor instance when document is encrypted.
     *
     * @private
     */
    _encrypt: _PdfEncryptor;
    /**
     * Document ID array from the trailer.
     *
     * @private
     */
    _ids: string[];
    /**
     * Permission flags from the encryption dictionary.
     *
     * @private
     */
    _permissionFlags: number;
    /**
     * Previous XRef offset.
     *
     * @private
     */
    _prevXRefOffset: number;
    /**
     * Index array used when writing XRef streams.
     *
     * @private
     */
    _indexes: Array<number>;
    /**
     * Collection of archived object streams.
     *
     * @private
     */
    _objectStreamCollection: Map<_PdfReference, _PdfArchievedStream>;
    /**
     * Offsets of objects written when saving.
     *
     * @private
     */
    _offsets: Array<number>;
    /**
     * Map of offset references to assist table writing.
     *
     * @private
     */
    _offsetReference: Map<_PdfReference, any>;
    /**
     * Current write object stream when saving as stream format.
     *
     * @private
     */
    _objectStream: _PdfArchievedStream;
    /**
     * Current length written so far during save.
     *
     * @private
     */
    _currentLength: number;
    /**
     * Buffer length used while saving.
     *
     * @private
     */
    _bufferLength: number;
    /**
     * Whether decoder (image extraction) is supported.
     *
     * @private
     */
    _isDecoderSupport: boolean;
    /**
     * Signature dictionary used during saving.
     *
     * @private
     */
    _signature: _PdfSignatureDictionary;
    /**
     * Collection of signatures present in the document.
     *
     * @private
     */
    _signatureCollection: PdfSignature[];
    /**
     * Whether cross reference is written as table.
     *
     * @private
     */
    _isCrossReferenceTable: boolean;
    /**
     * Whether cross reference is written as stream.
     *
     * @private
     */
    _isCrossReferenceStream: boolean;
    _objectCollection: _PdfMainObjectCollection;
    constructor(document: PdfDocument, password?: string);
    /**
     * Sets the starting XRef position for parsing.
     *
     * @private
     * @param {number} startXRef - The startxref offset to parse.
     * @returns {void} nothing.
     */
    _setStartXRef(startXRef: number): void;
    /**
     * Parses cross-reference structures and initializes trailer/root state.
     *
     * @private
     * @param {boolean} recoveryMode - If true, uses fallback indexing.
     * @returns {void} nothing.
     */
    _parse(recoveryMode: boolean): void;
    /**
     * Gets the XRef entry information for the given object index.
     *
     * @private
     * @param {number} i - Object number index.
     * @returns {_PdfObjectInformation|null} Entry info or null.
     */
    _getEntry(i: number): _PdfObjectInformation;
    /**
     * Fetches an indirect object by reference, handling caching and circular refs.
     *
     * @private
     * @param {_PdfReference} ref - Indirect reference to fetch.
     * @param {boolean} [suppressEncryption] - Whether to suppress decryption.
     * @returns {any} The fetched object.
     */
    _fetch(ref: _PdfReference, suppressEncryption?: boolean): any;
    /**
     * Fetches an uncompressed object from the file stream.
     *
     * @private
     * @param {_PdfReference} reference - Reference to the object.
     * @param {_PdfObjectInformation} xrefEntry - XRef entry describing the object.
     * @param {boolean} [makeFilter] - Whether to apply stream filters.
     * @returns {any} The parsed object.
     */
    _fetchUncompressed(reference: _PdfReference, xrefEntry: _PdfObjectInformation, makeFilter?: boolean): any;
    /**
     * Fetches an object stored inside an object stream (ObjStm).
     *
     * @private
     * @param {_PdfReference} ref - Reference to fetch.
     * @param {_PdfObjectInformation} xrefEntry - XRef entry for the object.
     * @returns {any} The fetched object.
     */
    _fetchCompressed(ref: _PdfReference, xrefEntry: _PdfObjectInformation): any;
    /**
     * Reads cross-reference structures (table/stream) starting from queued offsets.
     *
     * @private
     * @param {boolean} [recoveryMode=false] - If true, tries heuristic indexing.
     * @returns {_PdfDictionary} The trailer dictionary.
     */
    _readXRef(recoveryMode?: boolean): _PdfDictionary;
    /**
     * Reads a token string from a byte buffer starting at offset.
     *
     * @private
     * @param {Uint8Array} data - Buffer to read from.
     * @param {number} offset - Start offset.
     * @returns {string} The token read.
     */
    _readToken(data: Uint8Array, offset: number): string;
    /**
     * Skips bytes until the given sequence is found.
     *
     * @private
     * @param {Uint8Array} data - Buffer to search.
     * @param {number} offset - Starting offset.
     * @param {Uint8Array} what - Sequence to find.
     * @returns {number} Number of bytes skipped.
     */
    _skipUntil(data: Uint8Array, offset: number, what: Uint8Array): number;
    /**
     * Indexes objects by scanning the entire PDF stream when no valid XRef exists.
     *
     * @private
     * @returns {_PdfDictionary} Best trailer dictionary found.
     */
    _indexObjects(): _PdfDictionary;
    /**
     * Processes an XRef table and returns its trailer dictionary.
     *
     * @private
     * @param {_PdfParser} parser - Parser positioned after 'xref'.
     * @returns {_PdfDictionary} The trailer dictionary.
     */
    _processXRefTable(parser: _PdfParser): _PdfDictionary;
    /**
     * Reads entries from an XRef table subsection.
     *
     * @private
     * @param {_PdfParser} parser - Parser to read entries from.
     * @returns {_PdfCommand} The command following the table.
     */
    _readXRefTable(parser: _PdfParser): _PdfCommand;
    /**
     * Processes an XRef stream and returns its dictionary.
     *
     * @private
     * @param {_PdfStream} stream - The XRef stream.
     * @returns {_PdfDictionary} The stream dictionary.
     */
    _processXRefStream(stream: _PdfStream): _PdfDictionary;
    /**
     * Reads entries from an XRef stream into internal state.
     *
     * @private
     * @param {_PdfStream} stream - Stream to read.
     * @returns {void} nothing.
     */
    _readXRefStream(stream: _PdfStream): void;
    /**
     * Returns the document catalog (root) dictionary.
     *
     * @private
     * @returns {_PdfDictionary} The root dictionary.
     */
    _getCatalogObj(): _PdfDictionary;
    _flushBuffer(data: Array<number>): void;
    /**
     * Serializes and returns the full PDF bytes synchronously.
     *
     * @private
     * @returns {Uint8Array} Serialized document bytes.
     */
    _save(): Uint8Array;
    /**
     * Saves objects as a cross-reference stream.
     *
     * @private
     * @param {number} currentLength - Current file length prior to writing.
     * @param {number[]} buffer - Buffer to append to.
     * @returns {void} nothing.
     */
    _saveAsStream(currentLength: number, buffer: number[]): void;
    /**
     * Writes the XRef stream and related structures into the buffer.
     *
     * @private
     * @param {number[]} buffer - Buffer to write to.
     * @returns {void} nothing.
     */
    _writeXrefStream(buffer: number[]): void;
    /**
     * Writes an updated dictionary object to the output and records offsets.
     *
     * @private
     * @param {number} currentLength - Current output length.
     * @param {_PdfReference} key - Object reference.
     * @param {number[]} buffer - Output buffer.
     * @param {any} value - Object value.
     * @param {_CipherTransform} [cipher] - Optional cipher transform.
     * @returns {void} nothing.
     */
    _updatedDictionary(currentLength: number, key: _PdfReference, buffer: number[], value: any, // eslint-disable-line
    cipher?: _CipherTransform): void;
    /**
     * Writes an XRef table into the buffer.
     *
     * @private
     * @param {number[]} buffer - Buffer to write to.
     * @returns {void} nothing.
     */
    _writeXrefTable(buffer: number[]): void;
    /**
     * Writes low-level XRef text and trailer into the buffer.
     *
     * @private
     * @param {number[]} buffer - Buffer to append to.
     * @param {string} tempBuffer - Precomputed entry lines.
     * @param {number} newStartXref - Offset of the new xref.
     * @returns {void} nothing.
     */
    _writeXref(buffer: number[], tempBuffer: string, newStartXref: number): void;
    /**
     * Pads a numeric string with leading zeros to the desired length.
     *
     * @private
     * @param {string} value - Value to pad.
     * @param {number} length - Desired length.
     * @returns {string} Padded string.
     */
    _processString(value: string, length: number): string;
    /**
     * Copies trailer keys (Root/Info/Encrypt) into a new xref dictionary.
     *
     * @private
     * @param {_PdfDictionary} newXref - Dictionary to populate.
     * @returns {void} nothing.
     */
    _copyTrailer(newXref: _PdfDictionary): void;
    /**
     * Computes a message digest used for signature or ID updates.
     *
     * @private
     * @param {number} size - Current size used in the digest.
     * @returns {string} Hex digest string.
     */
    _computeMessageDigest(size: number): string;
    /**
     * Allocates the next object reference number.
     *
     * @private
     * @returns {_PdfReference} New reference object.
     */
    _getNextReference(): _PdfReference;
    /**
     * Writes a PDF object (dictionary, stream, array, number, or string) into the output
     * buffer, applying optional encryption and handling reference wrappers when present.
     *
     * @private
     * @param {_PdfDictionary | _PdfBaseStream | any} obj - The PDF object to serialize.
     * @param {number[]} buffer - The output buffer receiving encoded bytes.
     * @param {_PdfReference} [reference] - Optional object reference used to wrap the output in an `obj` / `endobj` container.
     * @param {_CipherTransform} [transform] - Optional cipher transform applied to encrypt stream or string values.
     * @param {boolean} [isCrossReference] - Indicates whether this object belongs to a cross-reference section.
     * @returns {void} nothing.
     */
    _writeObject(obj: _PdfDictionary | _PdfBaseStream | any, // eslint-disable-line
    buffer: Array<number>, reference?: _PdfReference, transform?: _CipherTransform, isCrossReference?: boolean): void;
    /**
     * Writes a dictionary object into the output buffer using the specified spacing
     * and optionally applies encryption or cross reference rules.
     *
     * @private
     * @param {_PdfDictionary} dictionary - The dictionary to serialize into the buffer.
     * @param {number[]} buffer - The output buffer receiving serialized bytes.
     * @param {string} spaceChar - The spacing string written between dictionary entries.
     * @param {_CipherTransform} [transform] - Optional cipher transform for encrypting values.
     * @param {boolean} [isCrossReference] - Indicates whether the dictionary belongs to a cross reference stream.
     * @returns {void} nothing.
     */
    _writeDictionary(dictionary: _PdfDictionary, buffer: Array<number>, spaceChar: string, transform?: _CipherTransform, isCrossReference?: boolean): void;
    /**
     * Ensures font-related dictionary entries are converted to references.
     *
     * @private
     * @param {_PdfDictionary} dictionary - Font dictionary to process.
     * @returns {void} nothing.
     */
    _writeFontDictionary(dictionary: _PdfDictionary): void;
    /**
     * Ensures a font-related subkey is stored as an indirect reference.
     *
     * @private
     * @param {string} key - Dictionary key to convert.
     * @param {_PdfDictionary} dictionary - Dictionary to modify.
     * @returns {void} nothing.
     */
    _createFontReference(key: string, dictionary: _PdfDictionary): void;
    /**
     * Writes a stream object into the output buffer, optionally applying encryption
     * or handling cross-reference stream rules.
     *
     * @private
     * @param {_PdfBaseStream} stream - The source PDF stream to write.
     * @param {number[]} buffer - The output buffer receiving the encoded stream.
     * @param {_CipherTransform} [transform] - Optional cipher transform used to encrypt stream data.
     * @param {boolean} [isCrossReference] - Indicates whether the stream is part of a cross-reference structure.
     * @returns {void} nothing.
     */
    _writeStream(stream: _PdfBaseStream, buffer: Array<number>, transform?: _CipherTransform, isCrossReference?: boolean): void;
    /**
     * Writes a value (name, reference, array, string, number, etc.) into the buffer.
     *
     * @private
     * @param {any} value - String to write.
     * @param {any} key - Destination buffer.
     * @param {Array<number>} buffer - buffer for the text.
     * @param {_CipherTransform} [transform] - String to write.
     * @param {boolean} [isCrossReference] - Destination buffer.
     * @returns {void} nothing.
     */
    _writeValue(value: any, key: any, buffer: Array<number>, transform?: _CipherTransform, isCrossReference?: boolean): void;
    /**
     * Writes a Unicode string as big-endian bytes into the buffer.
     *
     * @private
     * @param {string} value - String to write.
     * @param {Array<number>} buffer - Destination buffer.
     * @returns {void} nothing.
     */
    _writeUnicodeString(value: string, buffer: Array<number>): void;
    /**
     * Writes raw string characters into the numeric buffer.
     *
     * @private
     * @param {string} value - String to write.
     * @param {Array<number>} buffer - Destination buffer.
     * @returns {void} nothing.
     */
    _writeString(value: string, buffer: Array<number>): void;
    /**
     * Writes raw bytes into the numeric buffer.
     *
     * @private
     * @param {number[]} data - Bytes to write.
     * @param {Array<number>} buffer - Destination buffer.
     * @returns {void} nothing.
     */
    _writeBytes(data: number[], buffer: Array<number>): void;
    /**
     * Writes a multi-byte long integer into the buffer.
     *
     * @private
     * @param {number} value - Destination buffer.
     * @param {number} count - Destination buffer.
     * @param {Array<number>} buffer - Destination buffer.
     * @returns {void} nothing.
     */
    _writeLong(value: number, count: number, buffer: Array<number>): void;
    /**
     * Escapes special characters in a string for PDF string literals.
     *
     * @private
     * @param {string} value - Input string.
     * @returns {string} Escaped string.
     */
    _escapeString(value: string): string;
    _destroy(): void;
    _writeObjectCollection(objectCollection: Map<_PdfReference, any>, buffer: number[]): void;
    _saveAsTable(currentLength: number, buffer: number[]): void;
    _writeArchiveStream(objectStreamCollection: Map<_PdfReference, _PdfArchievedStream>, key: _PdfReference, value: any): void;
    _writeObjectToBuffer(key: _PdfReference, value: any, buffer: number[], // eslint-disable-line
    objectStreamCollection: Map<_PdfReference, _PdfArchievedStream>): void;
    _writeToBuffer(buffer: number[], key: any, value: any, cipher?: _CipherTransform): void;
    _getSortedReferences(collection: Map<_PdfReference, any>): Map<_PdfReference, any>;
    _saveAsync(): Promise<Uint8Array>;
    _writeStringAsync(value: string, buffer: Array<number>): Promise<void>;
    _writeObjectCollectionAsync(objectCollection: Map<_PdfReference, any>, buffer: number[]): Promise<void>;
    _flushBufferAsync(data: number[]): Promise<void>;
    _writeXrefStreamAsync(buffer: number[]): Promise<void>;
    _writeXrefTableAsync(buffer: number[]): Promise<void>;
    _saveAsStreamAsync(currentLength: number, buffer: number[]): Promise<void>;
    _saveAsTableAsync(currentLength: number, buffer: number[]): Promise<void>;
    _writeXrefAsync(buffer: number[], tempBuffer: string, newStartXref: number): Promise<void>;
}
/**
 * Represents metadata for a single object entry in the XRef table/stream.
 *
 * @private
 */
declare class _PdfObjectInformation {
    /** Object byte offset or object stream index. */
    offset: number;
    /** Generation number for the entry. */
    gen: number;
    /** Whether the object is stored uncompressed (in file) */
    uncompressed: boolean;
    /** Whether the entry is free. */
    free: boolean;
}
/**
 * Internal state used when parsing an XRef table across reads.
 *
 * @private
 */
declare class _PdfCrossTableState {
    /** Current entry index within the subsection. */
    entryNum: number;
    /** Stream position at start of subsection. */
    streamPos: number;
    /** Parser buffer state (first). */
    parserBuf1: any;
    /** Parser buffer state (second). */
    parserBuf2: any;
    /** First entry number of the subsection. */
    firstEntryNum: number;
    /** Number of entries in the subsection. */
    entryCount: number;
}
/**
 * State for parsing cross-reference streams (byte widths and ranges).
 *
 * @private
 */
declare class _PdfStreamState {
    /** Entry ranges (pairs of first,n). */
    entryRanges: number[];
    /** Byte widths for fields in the stream entries. */
    byteWidths: number[];
    /** Current entry index within the active range. */
    entryNum: number;
    /** Stream position used when resuming parsing. */
    streamPos: number;
}
/**
 * Helper that collects objects to write into an archived object stream (.objstm).
 *
 * @private
 */
declare class _PdfArchievedStream {
    /** Serialized index lines for the archive stream. */
    _indexes: string;
    /** Number of objects stored in this archived stream. */
    _length: number;
    /** Buffer of bytes for the archived stream content. */
    _updatedStream: number[];
    /** Parent cross-reference instance. */
    _crossReference: _PdfCrossReference;
    /** Reference assigned to the archived object stream. */
    _reference: _PdfReference;
    /** Accumulated XRef index text for the archive. */
    _archiveXRef: string;
    /** Collection of object numbers included in this archive. */
    _collection: number[];
    /** Offset where this archive will be written. */
    _archiveOffset: number;
    /**
     * Initializes a new archived stream helper.
     *
     * @private
     * @param {_PdfCrossReference} crossReference - Owner cross-reference.
     */
    constructor(crossReference: _PdfCrossReference);
    /**
     * Appends an object to the archived stream.
     *
     * @private
     * @param {_PdfReference} key - Reference of the object.
     * @param {_PdfDictionary} value - Object value to write.
     * @returns {void} nothing.
     */
    _writeObject(key: _PdfReference, value: _PdfDictionary): void;
    /**
     * Saves the archived stream into the provided buffer and updates offsets.
     *
     * @private
     * @param {number[]} buffer - Output buffer to append to.
     * @param {number} currentLength - Current length before writing.
     * @returns {void} nothing.
     */
    _save(buffer: number[], currentLength: number): void;
}
/**
 * Represents the main object collection that will be written into the file.
 * It collects and orders objects to be saved.
 *
 * @private
 */
declare class _PdfMainObjectCollection {
    /** Pointer into the ordered collection. */
    _pointer: number;
    /** Array of references included. */
    _reference: _PdfReference[];
    /** Backing cache map from the cross-reference. */
    _cache: Map<_PdfReference, any>;
    /** Parent cross-reference instance. */
    _crossReference: _PdfCrossReference;
    /** Map of main objects to be written. */
    _mainObjectCollection: Map<_PdfReference, any>;
    /**
     * Initializes a new instance of the `_PdfMainObjectCollection` class.
     *
     * @private
     * @param { _PdfCrossReference } collection - The cross-reference collection containing the PDF objects.
     * ```typescript
     * // Load an existing PDF document
     * let document: PdfDocument = new PdfDocument(data);
     * // Create a new object collection instance
     * let mainObjectCollection = new _PdfMainObjectCollection(document._crossReference);
     * // Access the main object collection
     * let objects = mainObjectCollection._mainObjectCollection;
     * // Save the document
     * document.save('output.pdf');
     * // Destroy the document
     * document.destroy();
     */
    constructor(collection: _PdfCrossReference);
    /**
     * Parses the accumulated main object collection, expanding referenced objects.
     *
     * @private
     * @returns {Map<_PdfReference, any>} The populated main object collection.
     */
    _parseObjectCollection(): Map<_PdfReference, any>;
    /**
     * Adds an object to the main collection.
     *
     * @private
     * @param {_PdfReference} key - Object reference.
     * @param {any} value - Object value.
     * @returns {void} nothing.
     */
    _addToMainObjectCollection(key: _PdfReference, value: any): void;
    /**
     * Fetches a reference and parses it into the main collection.
     *
     * @private
     * @param {_PdfReference} reference - Reference to fetch and parse.
     * @returns {void} nothing.
     */
    _parseFetchValue(reference: _PdfReference): void;
    /**
     * Internal parser that inspects a value and ensures referenced objects are included.
     *
     * @private
     * @param {_PdfReference} key - Reference for the value.
     * @param {any} value - Value to inspect.
     * @returns {void} nothing.
     */
    _parse(key: _PdfReference, value: any): void;
    /**
     * Adds any remaining cached objects into the main collection.
     *
     * @private
     * @returns {void} nothing.
     */
    _addReferencesToMainCollection(): void;
    /**
     * Walks a dictionary and ensures referenced objects are included.
     *
     * @private
     * @param {_PdfDictionary} element - Dictionary to scan.
     * @returns {void} nothing.
     */
    _parseDictionary(element: _PdfDictionary): void;
    /**
     * Parses a stream object dictionary and includes its referenced objects.
     *
     * @private
     * @param {_PdfReference} key - Reference of the stream.
     * @param {_PdfBaseStream} element - The stream to parse.
     * @returns {void} nothing.
     */
    _parseStream(key: _PdfReference, element: _PdfBaseStream): void;
}
export {};