pdf-lite 1.2.1 → 1.3.1

package/dist/acroform/manager.d.ts

@@ -11,12 +11,12 @@ export declare class PdfAcroFormManager {
      * Checks if the document contains AcroForm fields.
      * @returns True if the document has AcroForm fields, false otherwise
      */
-    hasAcroForm(): Promise<boolean>;
+    exists(): Promise<boolean>;
     /**
      * Gets the AcroForm object from the document catalog.
      * @returns The AcroForm object or null if not found
      */
-    getAcroForm(): Promise<PdfAcroForm | null>;
+    read(): Promise<PdfAcroForm | null>;
     /**
      * Writes the provided AcroForm to the associated PDF document.
      * @param acroForm The AcroForm instance to serialize into the document.

package/dist/acroform/manager.js

@@ -12,9 +12,9 @@ export class PdfAcroFormManager {
      * Checks if the document contains AcroForm fields.
      * @returns True if the document has AcroForm fields, false otherwise
      */
-    async hasAcroForm() {
+    async exists() {
         try {
-            const acroForm = await this.getAcroForm();
+            const acroForm = await this.read();
             return acroForm !== null;
         }
         catch {
@@ -25,7 +25,7 @@ export class PdfAcroFormManager {
      * Gets the AcroForm object from the document catalog.
      * @returns The AcroForm object or null if not found
      */
-    async getAcroForm() {
+    async read() {
         return await PdfAcroForm.fromDocument(this.document);
     }
     /**

package/dist/core/decoder.d.ts

@@ -1,6 +1,6 @@
 import { PdfObject } from './objects/pdf-object.js';
 import { PdfToken } from './tokens/token.js';
-import { IncrementalParser } from './incremental-parser.js';
+import { IncrementalParser } from './parser/incremental-parser.js';
 /**
  * Decodes PDF tokens into PDF objects.
  * Handles parsing of all PDF object types including dictionaries, arrays, streams, and xref tables.

package/dist/core/decoder.js

@@ -36,7 +36,7 @@ import { PdfComment } from './objects/pdf-comment.js';
 import { PdfStartXRefToken } from './tokens/start-xref-token.js';
 import { PdfStartXRef } from './objects/pdf-start-xref.js';
 import { PdfWhitespaceToken } from './tokens/whitespace-token.js';
-import { IncrementalParser } from './incremental-parser.js';
+import { IncrementalParser } from './parser/incremental-parser.js';
 import { concatUint8Arrays } from '../utils/concatUint8Arrays.js';
 const DEFAULT_MAX_BUFFER_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
 /**
@@ -179,7 +179,7 @@ export class PdfDecoder extends IncrementalParser {
             out = new PdfBoolean(token.value);
         }
         else if (token instanceof PdfHexadecimalToken) {
-            out = new PdfHexadecimal(token.raw, 'hex');
+            out = new PdfHexadecimal(token.raw, 'hex', token.originalBytes);
         }
         else if (token instanceof PdfNullToken) {
             out = new PdfNull();
@@ -188,7 +188,7 @@ export class PdfDecoder extends IncrementalParser {
             out = new PdfObjectReference(token.objectNumber, token.generationNumber);
         }
         else if (token instanceof PdfStringToken) {
-            out = new PdfString(token.value);
+            out = new PdfString(token.value, token.originalBytes);
         }
         else {
             throw new Error(`Unknown primitive token type: ${token.type}`);

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
 export * from './decoder.js';
 export * from './generators.js';
-export * from './incremental-parser.js';
+export * from './parser/incremental-parser.js';
 export * from './objects/pdf-array.js';
 export * from './objects/pdf-boolean.js';
 export * from './objects/pdf-comment.js';
@@ -18,7 +18,7 @@ export * from './objects/pdf-stream.js';
 export * from './objects/pdf-string.js';
 export * from './objects/pdf-trailer.js';
 export * from './objects/pdf-xref-table.js';
-export * from './parser.js';
+export * from './parser/parser.js';
 export * from './ref.js';
 export * from './serializer.js';
 export * from './streams/object-stream.js';

package/dist/core/index.js

@@ -1,6 +1,6 @@
 export * from './decoder.js';
 export * from './generators.js';
-export * from './incremental-parser.js';
+export * from './parser/incremental-parser.js';
 export * from './objects/pdf-array.js';
 export * from './objects/pdf-boolean.js';
 export * from './objects/pdf-comment.js';
@@ -18,7 +18,7 @@ export * from './objects/pdf-stream.js';
 export * from './objects/pdf-string.js';
 export * from './objects/pdf-trailer.js';
 export * from './objects/pdf-xref-table.js';
-export * from './parser.js';
+export * from './parser/parser.js';
 export * from './ref.js';
 export * from './serializer.js';
 export * from './streams/object-stream.js';

package/dist/core/objects/pdf-array.d.ts

@@ -9,4 +9,5 @@ export declare class PdfArray<T extends PdfObject = PdfObject> extends PdfObject
     protected tokenize(): import("../index.js").PdfToken[];
     clone(): this;
     isModified(): boolean;
+    setImmutable(immutable?: boolean): void;
 }

package/dist/core/objects/pdf-array.js

@@ -39,4 +39,8 @@ export class PdfArray extends PdfObject {
     isModified() {
         return (super.isModified() || this.items.some((item) => item.isModified()));
     }
+    setImmutable(immutable) {
+        super.setImmutable(immutable);
+        this.items.forEach((item) => item.setImmutable(immutable));
+    }
 }

package/dist/core/objects/pdf-dictionary.d.ts

@@ -24,4 +24,5 @@ export declare class PdfDictionary<T extends PdfDictionaryEntries = PdfDictionar
     copyFrom(other: PdfDictionary<any>): void;
     clone(): this;
     isModified(): boolean;
+    setImmutable(immutable?: boolean): void;
 }

package/dist/core/objects/pdf-dictionary.js

@@ -28,6 +28,9 @@ export class PdfDictionary extends PdfObject {
         }
     }
     set(key, value) {
+        if (this.isImmutable()) {
+            throw new Error('Cannot modify an immutable PdfDictionary');
+        }
         const currentValue = this.get(key);
         if (currentValue !== value && !currentValue?.equals(value)) {
             this.modified = true;
@@ -47,6 +50,9 @@ export class PdfDictionary extends PdfObject {
         this.#entries.set(new PdfName(key), value);
     }
     delete(key) {
+        if (this.isImmutable()) {
+            throw new Error('Cannot modify an immutable PdfDictionary');
+        }
         if (this.has(key)) {
             this.modified = true;
         }
@@ -141,4 +147,10 @@ export class PdfDictionary extends PdfObject {
         return (super.isModified() ||
             Array.from(this.#entries.values()).some((v) => v?.isModified()));
     }
+    setImmutable(immutable) {
+        super.setImmutable(immutable);
+        for (const value of this.#entries.values()) {
+            value?.setImmutable(immutable);
+        }
+    }
 }

package/dist/core/objects/pdf-hexadecimal.d.ts

@@ -6,8 +6,15 @@ export declare class PdfHexadecimal extends PdfObject {
      * The raw byte value represented by this hexadecimal object.
      * NB: This is  the hexadecimal representation, not the actual byte values.
      */
-    raw: ByteArray;
-    constructor(value: string | ByteArray, format?: 'hex' | 'bytes');
+    private _raw;
+    /**
+     * Original bytes from the PDF file, including angle brackets.
+     * Used to preserve exact formatting for incremental updates.
+     */
+    private _originalBytes?;
+    constructor(value: string | ByteArray, format?: 'hex' | 'bytes', originalBytes?: ByteArray);
+    get raw(): ByteArray;
+    set raw(raw: ByteArray);
     static toHexadecimal(data: string | ByteArray): PdfHexadecimal;
     get bytes(): ByteArray;
     toHexBytes(): ByteArray;

package/dist/core/objects/pdf-hexadecimal.js

@@ -9,8 +9,13 @@ export class PdfHexadecimal extends PdfObject {
      * The raw byte value represented by this hexadecimal object.
      * NB: This is  the hexadecimal representation, not the actual byte values.
      */
-    raw;
-    constructor(value, format = 'hex') {
+    _raw;
+    /**
+     * Original bytes from the PDF file, including angle brackets.
+     * Used to preserve exact formatting for incremental updates.
+     */
+    _originalBytes;
+    constructor(value, format = 'hex', originalBytes) {
         super();
         let bytes;
         if (format === 'bytes') {
@@ -19,7 +24,20 @@ export class PdfHexadecimal extends PdfObject {
         else {
             bytes = value instanceof Uint8Array ? value : stringToBytes(value);
         }
-        this.raw = bytes;
+        this._raw = bytes;
+        this._originalBytes = originalBytes;
+    }
+    get raw() {
+        return this._raw;
+    }
+    set raw(raw) {
+        if (this.isImmutable()) {
+            throw new Error('Cannot modify an immutable PdfHexadecimal');
+        }
+        this.setModified();
+        this._raw = raw;
+        // Clear original bytes when modified
+        this._originalBytes = undefined;
     }
     static toHexadecimal(data) {
         return new PdfHexadecimal(data, 'bytes');
@@ -34,9 +52,11 @@ export class PdfHexadecimal extends PdfObject {
         return bytesToString(this.toHexBytes());
     }
     tokenize() {
-        return [new PdfHexadecimalToken(this.raw)];
+        return [new PdfHexadecimalToken(this.raw, this._originalBytes)];
     }
     clone() {
-        return new PdfHexadecimal(new Uint8Array(this.raw));
+        return new PdfHexadecimal(new Uint8Array(this.raw), 'hex', this._originalBytes
+            ? new Uint8Array(this._originalBytes)
+            : undefined);
     }
 }

package/dist/core/objects/pdf-indirect-object.d.ts

@@ -8,20 +8,22 @@ export declare class PdfIndirectObject<T extends PdfObject = PdfObject> extends
     offset: Ref<number>;
     encryptable?: boolean;
     orderIndex?: number;
-    constructor(options: {
+    constructor(options?: {
         objectNumber?: number;
         generationNumber?: number;
-        content: T;
+        content?: T;
         offset?: number | Ref<number>;
         encryptable?: boolean;
-    } | T);
+    } | T | PdfIndirectObject);
     get reference(): PdfObjectReference;
     isEncryptable(): boolean;
     static createPlaceholder<T extends PdfObject>(objectNumber?: number, generationNumber?: number, content?: T): PdfIndirectObject<T extends unknown ? PdfNull : T>;
     inPdf(): boolean;
     matchesReference(ref?: PdfObjectReference): boolean;
     protected tokenize(): import("../index.js").PdfToken[];
+    copyFrom(other: PdfIndirectObject): void;
     clone(): this;
     order(): number;
     isModified(): boolean;
+    setImmutable(immutable?: boolean): void;
 }

package/dist/core/objects/pdf-indirect-object.js

@@ -14,19 +14,25 @@ export class PdfIndirectObject extends PdfObjectReference {
     encryptable;
     orderIndex;
     constructor(options) {
+        if (options instanceof PdfIndirectObject) {
+            super(options.objectNumber, options.generationNumber);
+            this.content = options.content.clone();
+            this.offset = options.offset.clone();
+            return;
+        }
         if (options instanceof PdfObject) {
             super(-1, 0);
             this.content = options;
             this.offset = new Ref(0);
             return;
         }
-        super(options.objectNumber ?? -1, options.generationNumber ?? 0);
-        this.content = options.content;
+        super(options?.objectNumber ?? -1, options?.generationNumber ?? 0);
+        this.content = options?.content ?? new PdfNull();
         this.offset =
-            options.offset instanceof Ref
+            options?.offset instanceof Ref
                 ? options.offset
-                : new Ref(options.offset ?? 0);
-        this.encryptable = options.encryptable;
+                : new Ref(options?.offset ?? 0);
+        this.encryptable = options?.encryptable;
     }
     get reference() {
         return new Proxy(this, {
@@ -81,6 +87,13 @@ export class PdfIndirectObject extends PdfObjectReference {
             new PdfEndObjectToken(),
         ];
     }
+    copyFrom(other) {
+        this.objectNumber = other.objectNumber;
+        this.generationNumber = other.generationNumber;
+        this.content = other.content.clone();
+        this.offset = other.offset.clone();
+        this.modified = true;
+    }
     clone() {
         return new PdfIndirectObject({
             objectNumber: this.objectNumber,
@@ -97,4 +110,9 @@ export class PdfIndirectObject extends PdfObjectReference {
             this.content.isModified() ||
             this.offset.isModified);
     }
+    setImmutable(immutable) {
+        super.setImmutable(immutable);
+        this.content.setImmutable(immutable);
+        this.offset.setImmutable(immutable);
+    }
 }

package/dist/core/objects/pdf-number.js

@@ -45,6 +45,9 @@ export class PdfNumber extends PdfObject {
         return this.#value.resolve();
     }
     set value(value) {
+        if (this.isImmutable()) {
+            throw new Error('Cannot modify an immutable PdfNumber');
+        }
         this.#value.update(value);
     }
     onChange(callback) {

package/dist/core/objects/pdf-object.d.ts

@@ -7,6 +7,8 @@ export declare abstract class PdfObject {
     postTokens?: PdfToken[];
     /** Indicates whether the object has been modified. By default, assume it has been modified because it's a new object */
     protected modified: boolean;
+    /** Indicates whether the object is immutable (cannot be modified) */
+    protected immutable: boolean;
     /** Tokenizes the object into an array of PdfTokens */
     protected abstract tokenize(): PdfToken[];
     /** The type of this PDF object */
@@ -15,6 +17,10 @@ export declare abstract class PdfObject {
     isModified(): boolean;
     /** Sets the modified state of the object. Override this method if the modified state is determined differently */
     setModified(modified?: boolean): void;
+    /** Indicates whether the object is immutable (cannot be modified) */
+    isImmutable(): boolean;
+    /** Sets the immutable state of the object */
+    setImmutable(immutable?: boolean): void;
     /** Converts the object to an array of PdfTokens, including any pre or post tokens */
     toTokens(): PdfToken[];
     /** Converts the object to a ByteArray, optionally padding to a specified length */

package/dist/core/objects/pdf-object.js

@@ -7,6 +7,8 @@ export class PdfObject {
     postTokens;
     /** Indicates whether the object has been modified. By default, assume it has been modified because it's a new object */
     modified = true;
+    /** Indicates whether the object is immutable (cannot be modified) */
+    immutable = false;
     /** The type of this PDF object */
     get objectType() {
         return this.constructor.name;
@@ -19,6 +21,14 @@ export class PdfObject {
     setModified(modified = true) {
         this.modified = modified;
     }
+    /** Indicates whether the object is immutable (cannot be modified) */
+    isImmutable() {
+        return this.immutable;
+    }
+    /** Sets the immutable state of the object */
+    setImmutable(immutable = true) {
+        this.immutable = immutable;
+    }
     /** Converts the object to an array of PdfTokens, including any pre or post tokens */
     toTokens() {
         return [

package/dist/core/objects/pdf-stream.js

@@ -44,6 +44,9 @@ export class PdfStream extends PdfObject {
         return this.original.slice(0, length);
     }
     set raw(data) {
+        if (this.isImmutable()) {
+            throw new Error('Cannot modify an immutable PdfStream');
+        }
         this.setModified();
         this.original = data;
         this.header.set('Length', new PdfNumber(data.length));

package/dist/core/objects/pdf-string.d.ts

@@ -6,9 +6,19 @@ export declare class PdfString extends PdfObject {
      * The raw bytes of the PDF string.
      */
     private _raw;
-    constructor(raw: ByteArray | string);
+    /**
+     * Original bytes from the PDF file, including parentheses and escape sequences.
+     * Used to preserve exact formatting for incremental updates.
+     */
+    private _originalBytes?;
+    constructor(raw: ByteArray | string, originalBytes?: ByteArray);
     get raw(): ByteArray;
     set raw(raw: ByteArray);
+    /**
+     * Checks if this string is UTF-16BE encoded (has UTF-16BE BOM).
+     * UTF-16BE strings start with the byte order mark 0xFE 0xFF.
+     */
+    get isUTF16BE(): boolean;
     get value(): string;
     protected tokenize(): PdfStringToken[];
     clone(): this;

package/dist/core/objects/pdf-string.js

@@ -10,7 +10,12 @@ export class PdfString extends PdfObject {
      * The raw bytes of the PDF string.
      */
     _raw;
-    constructor(raw) {
+    /**
+     * Original bytes from the PDF file, including parentheses and escape sequences.
+     * Used to preserve exact formatting for incremental updates.
+     */
+    _originalBytes;
+    constructor(raw, originalBytes) {
         super();
         if (typeof raw === 'string') {
             // Check if the string contains non-ASCII characters
@@ -26,28 +31,41 @@ export class PdfString extends PdfObject {
         else {
             this._raw = raw;
         }
+        this._originalBytes = originalBytes;
     }
     get raw() {
         return this._raw;
     }
     set raw(raw) {
+        if (this.isImmutable()) {
+            throw new Error('Cannot modify an immutable PdfString');
+        }
         this.setModified();
         this._raw = raw;
+        // Clear original bytes when modified
+        this._originalBytes = undefined;
+    }
+    /**
+     * Checks if this string is UTF-16BE encoded (has UTF-16BE BOM).
+     * UTF-16BE strings start with the byte order mark 0xFE 0xFF.
+     */
+    get isUTF16BE() {
+        return (this.raw.length >= 2 && this.raw[0] === 0xfe && this.raw[1] === 0xff);
     }
     get value() {
         // Check for UTF-16BE BOM (0xFE 0xFF)
-        if (this.raw.length >= 2 &&
-            this.raw[0] === 0xfe &&
-            this.raw[1] === 0xff) {
+        if (this.isUTF16BE) {
             return decodeFromUTF16BE(this.raw);
         }
         // Default: use PDFDocEncoding
         return decodeFromPDFDocEncoding(this.raw);
     }
     tokenize() {
-        return [new PdfStringToken(this.raw)];
+        return [new PdfStringToken(this.raw, this._originalBytes)];
     }
     clone() {
-        return new PdfString(new Uint8Array(this.raw));
+        return new PdfString(new Uint8Array(this.raw), this._originalBytes
+            ? new Uint8Array(this._originalBytes)
+            : undefined);
     }
 }

package/dist/core/ref.d.ts

@@ -23,6 +23,7 @@ export declare class Ref<T> {
     /** Registered callbacks for update notifications */
     callbacks: Array<RefUpdateCallback<T>>;
     isModified: boolean;
+    protected immutable: boolean;
     /**
      * Creates a new Ref with an initial value.
      *
@@ -30,6 +31,8 @@ export declare class Ref<T> {
      * @throws Error if attempting to create a self-referencing Ref
      */
     constructor(value: T | Ref<T>);
+    setImmutable(immutable?: boolean): void;
+    isImmutable(): boolean;
     /**
      * Updates the reference to a new value or another Ref.
      * Notifies all registered callbacks of the change.
@@ -56,4 +59,6 @@ export declare class Ref<T> {
      * @param callback - The function to call on value updates
      */
     onUpdate(callback: RefUpdateCallback<T>): void;
+    /** Creates a new Ref with the same resolved value. */
+    clone(): Ref<T>;
 }

package/dist/core/ref.js

@@ -17,6 +17,7 @@ export class Ref {
     /** Registered callbacks for update notifications */
     callbacks = [];
     isModified = false;
+    immutable = false;
     /**
      * Creates a new Ref with an initial value.
      *
@@ -29,6 +30,12 @@ export class Ref {
         }
         this.value = value;
     }
+    setImmutable(immutable = true) {
+        this.immutable = immutable;
+    }
+    isImmutable() {
+        return this.immutable;
+    }
     /**
      * Updates the reference to a new value or another Ref.
      * Notifies all registered callbacks of the change.
@@ -42,6 +49,9 @@ export class Ref {
         const resolvedNewValue = newValue instanceof Ref ? newValue.resolve() : newValue;
         const oldValue = this.resolve();
         if (oldValue !== resolvedNewValue) {
+            if (this.immutable) {
+                throw new Error(`Cannot update an immutable Ref (${oldValue} -> ${resolvedNewValue})`);
+            }
             this.isModified = true;
         }
         this.value = newValue;
@@ -81,4 +91,8 @@ export class Ref {
     onUpdate(callback) {
         this.callbacks.push(callback);
     }
+    /** Creates a new Ref with the same resolved value. */
+    clone() {
+        return new Ref(this.resolve());
+    }
 }

package/dist/core/serializer.d.ts

@@ -1,5 +1,5 @@
 import { ByteArray } from '../types.js';
-import { Parser } from './parser.js';
+import { Parser } from './parser/parser.js';
 import { PdfToken } from './tokens/token.js';
 /**
  * Serializes PDF tokens into a byte stream.

package/dist/core/serializer.js

@@ -1,4 +1,4 @@
-import { Parser } from './parser.js';
+import { Parser } from './parser/parser.js';
 import { PdfByteOffsetToken } from './tokens/byte-offset-token.js';
 /**
  * Serializes PDF tokens into a byte stream.

package/dist/core/tokeniser.d.ts

@@ -1,7 +1,7 @@
-import { IncrementalParser } from './incremental-parser.js';
+import { IncrementalParser } from './parser/incremental-parser.js';
 import { PdfObject } from './objects/pdf-object.js';
 import { PdfToken } from './tokens/token.js';
-import { Parser } from './parser.js';
+import { Parser } from './parser/parser.js';
 import { ByteArray } from '../types.js';
 /**
  * Type alias for a parser that converts bytes to PDF tokens.