@libpdf/core 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -332,7 +332,7 @@ declare class PdfDict implements PdfPrimitive {
   /**
    * Get value for key. Key can be string or PdfName.
    */
-  get(key: PdfName | string): PdfObject | undefined;
+  get(key: PdfName | string, resolver?: RefResolver): PdfObject | undefined;
   /**
    * Set value for key. Key can be string or PdfName.
    */
@@ -354,15 +354,19 @@ declare class PdfDict implements PdfPrimitive {
    */
   [Symbol.iterator](): Iterator<[PdfName, PdfObject]>;
   /**
-   * Typed getters
+   * Typed getters.
+   *
+   * All typed getters accept an optional resolver function. When provided,
+   * if the value is a PdfRef, it will be automatically dereferenced.
+   * This prevents the common bug of forgetting to handle indirect references.
    */
-  getName(key: string): PdfName | undefined;
-  getNumber(key: string): PdfNumber | undefined;
-  getString(key: string): PdfString | undefined;
-  getArray(key: string): PdfArray | undefined;
-  getDict(key: string): PdfDict | undefined;
+  getName(key: string, resolver?: RefResolver): PdfName | undefined;
+  getNumber(key: string, resolver?: RefResolver): PdfNumber | undefined;
+  getString(key: string, resolver?: RefResolver): PdfString | undefined;
+  getArray(key: string, resolver?: RefResolver): PdfArray | undefined;
+  getDict(key: string, resolver?: RefResolver): PdfDict | undefined;
   getRef(key: string): PdfRef | undefined;
-  getBool(key: string): PdfBool | undefined;
+  getBool(key: string, resolver?: RefResolver): PdfBool | undefined;
   /**
    * Create a shallow clone of this dictionary.
    * Values are shared, not deep-copied.
@@ -518,6 +522,19 @@ declare class PdfStream extends PdfDict {
  */
 type PdfObject = PdfNull | PdfBool | PdfNumber | PdfName | PdfString | PdfRef | PdfArray | PdfDict | PdfStream | PdfRaw;
 //#endregion
+//#region src/helpers/types.d.ts
+/**
+ * Function type for resolving a PdfRef to its target PdfObject.
+ *
+ * This is the standard resolver signature used throughout the library
+ * for dereferencing indirect object references. All PDF data is loaded
+ * into memory at parse time, so resolution is synchronous.
+ *
+ * @param ref - The indirect reference to resolve
+ * @returns The resolved object, or null if not found
+ */
+type RefResolver = (ref: PdfRef) => PdfObject | null;
+//#endregion
 //#region src/io/scanner.d.ts
 /**
  * Scanner - the lowest-level byte reader for PDF parsing.
@@ -595,15 +612,6 @@ type XRefEntry = {
 };
 //#endregion
 //#region src/document/object-registry.d.ts
-/**
- * Function to resolve objects not yet in the registry.
- * Called when resolve() encounters an unknown reference.
- *
- * This is synchronous because all PDF data is loaded into memory
- * at parse time. The resolver simply parses objects on demand from
- * the in-memory buffer.
- */
-type ObjectResolver = (ref: PdfRef) => PdfObject | null;
 /**
  * Registry for managing PDF objects and their references.
  *
@@ -637,7 +645,7 @@ declare class ObjectRegistry {
   /**
    * Set the resolver for fetching objects not yet in the registry.
    */
-  setResolver(resolver: ObjectResolver): void;
+  setResolver(resolver: RefResolver): void;
   /**
    * Get the next object number that will be assigned.
    */
@@ -4502,12 +4510,6 @@ declare class StandardSecurityHandler {
 }
 //#endregion
 //#region src/document/name-tree.d.ts
-/**
- * Function to resolve a reference to its object.
- *
- * Synchronous because all PDF data is loaded into memory at parse time.
- */
-type Resolver = (ref: PdfRef) => PdfObject | null;
 /**
  * PDF Name Tree reader.
  *
@@ -4518,7 +4520,7 @@ declare class NameTree {
   private readonly root;
   private readonly resolver;
   private cache;
-  constructor(root: PdfDict, resolver: Resolver);
+  constructor(root: PdfDict, resolver: RefResolver);
   /**
    * Lookup a single key using binary search.
    * Uses /Limits on intermediate nodes to skip subtrees.
@@ -4625,7 +4627,7 @@ declare class PDFPageTree {
   /**
    * Load and build the page tree by walking from the root.
    */
-  static load(pagesRef: PdfRef, getObject: (ref: PdfRef) => PdfObject | null): PDFPageTree;
+  static load(pagesRef: PdfRef, getObject: RefResolver): PDFPageTree;
   /**
    * Create an empty page tree.
    * Note: This creates a minimal tree without a backing PDF structure.
@@ -4756,10 +4758,6 @@ declare class PDFContext {
    * so this operation never requires I/O.
    */
   resolve(ref: PdfRef): PdfObject | null;
-  /**
-   * Get an object by reference (sync, only if already loaded).
-   */
-  getObject(ref: PdfRef): PdfObject | null;
   /**
    * Get the reference for an object.
    */
@@ -4888,8 +4886,8 @@ declare class PDFPage {
   /** The page index (0-based) */
   readonly index: number;
   /** Document context for registering objects */
-  private readonly ctx?;
-  constructor(ref: PdfRef, dict: PdfDict, index: number, ctx?: PDFContext);
+  private readonly ctx;
+  constructor(ref: PdfRef, dict: PdfDict, index: number, ctx: PDFContext);
   /**
    * Get the MediaBox (page boundary).
    *
@@ -4962,7 +4960,9 @@ declare class PDFPage {
   /**
    * Get the page's Resources dictionary.
    *
-   * Creates an empty one if it doesn't exist.
+   * If Resources is a reference, it's dereferenced.
+   * If Resources doesn't exist or is inherited from a parent,
+   * a new empty dict is created on this page.
    */
   getResources(): PdfDict;
   /**

package/dist/index.mjs

@@ -9,7 +9,7 @@ import { createCMSECDSASignature } from "pkijs";
 import { base64 } from "@scure/base";
 
 //#region package.json
-var version = "0.1.0";
+var version = "0.1.1";
 
 //#endregion
 //#region src/objects/pdf-array.ts
@@ -403,6 +403,69 @@ var PdfName = class PdfName {
 	}
 };
 
+//#endregion
+//#region src/objects/pdf-ref.ts
+/**
+* Default cache size for PdfRef interning.
+* Object references tend to be more numerous than names in typical PDFs.
+*/
+const DEFAULT_REF_CACHE_SIZE = 2e4;
+/**
+* PDF indirect reference (interned).
+*
+* In PDF: `1 0 R`, `42 0 R`
+*
+* References are interned using an LRU cache to prevent unbounded memory growth.
+* `PdfRef.of(1, 0) === PdfRef.of(1, 0)` as long as both are in cache.
+* Use `.of()` to get or create instances.
+*/
+var PdfRef = class PdfRef {
+	get type() {
+		return "ref";
+	}
+	static cache = new LRUCache(DEFAULT_REF_CACHE_SIZE);
+	constructor(objectNumber, generation) {
+		this.objectNumber = objectNumber;
+		this.generation = generation;
+	}
+	/**
+	* Get or create an interned PdfRef for the given object/generation pair.
+	*/
+	static of(objectNumber, generation = 0) {
+		const key$1 = `${objectNumber} ${generation}`;
+		let cached = PdfRef.cache.get(key$1);
+		if (!cached) {
+			cached = new PdfRef(objectNumber, generation);
+			PdfRef.cache.set(key$1, cached);
+		}
+		return cached;
+	}
+	/**
+	* Clear the reference cache.
+	*
+	* Useful for long-running applications that process many PDFs
+	* and want to reclaim memory between documents.
+	*/
+	static clearCache() {
+		PdfRef.cache.clear();
+	}
+	/**
+	* Get the current size of the LRU cache.
+	*/
+	static get cacheSize() {
+		return PdfRef.cache.size;
+	}
+	/**
+	* Returns the PDF syntax representation: "1 0 R"
+	*/
+	toString() {
+		return `${this.objectNumber} ${this.generation} R`;
+	}
+	toBytes(writer) {
+		writer.writeAscii(`${this.objectNumber} ${this.generation} R`);
+	}
+};
+
 //#endregion
 //#region src/objects/pdf-dict.ts
 /**
@@ -441,9 +504,11 @@ var PdfDict = class PdfDict {
 	/**
 	* Get value for key. Key can be string or PdfName.
 	*/
-	get(key$1) {
+	get(key$1, resolver) {
 		const name = typeof key$1 === "string" ? PdfName.of(key$1) : key$1;
-		return this.entries.get(name);
+		const value = this.entries.get(name);
+		if (resolver && value?.type === "ref") return resolver(value) ?? void 0;
+		return value;
 	}
 	/**
 	* Set value for key. Key can be string or PdfName.
@@ -482,34 +547,38 @@ var PdfDict = class PdfDict {
 		yield* this.entries;
 	}
 	/**
-	* Typed getters
+	* Typed getters.
+	*
+	* All typed getters accept an optional resolver function. When provided,
+	* if the value is a PdfRef, it will be automatically dereferenced.
+	* This prevents the common bug of forgetting to handle indirect references.
 	*/
-	getName(key$1) {
-		const value = this.get(key$1);
+	getName(key$1, resolver) {
+		const value = this.get(key$1, resolver);
 		return value?.type === "name" ? value : void 0;
 	}
-	getNumber(key$1) {
-		const value = this.get(key$1);
+	getNumber(key$1, resolver) {
+		const value = this.get(key$1, resolver);
 		return value?.type === "number" ? value : void 0;
 	}
-	getString(key$1) {
-		const value = this.get(key$1);
+	getString(key$1, resolver) {
+		const value = this.get(key$1, resolver);
 		return value?.type === "string" ? value : void 0;
 	}
-	getArray(key$1) {
-		const value = this.get(key$1);
+	getArray(key$1, resolver) {
+		const value = this.get(key$1, resolver);
 		return value?.type === "array" ? value : void 0;
 	}
-	getDict(key$1) {
-		const value = this.get(key$1);
+	getDict(key$1, resolver) {
+		const value = this.get(key$1, resolver);
 		return value?.type === "dict" ? value : void 0;
 	}
 	getRef(key$1) {
 		const value = this.get(key$1);
 		return value?.type === "ref" ? value : void 0;
 	}
-	getBool(key$1) {
-		const value = this.get(key$1);
+	getBool(key$1, resolver) {
+		const value = this.get(key$1, resolver);
 		return value?.type === "bool" ? value : void 0;
 	}
 	/**
@@ -2589,69 +2658,6 @@ const drawXObject = (name) => Operator.of(Op.DrawXObject, name);
 const beginMarkedContent = (tag) => Operator.of(Op.BeginMarkedContent, tag);
 const endMarkedContent = () => Operator.of(Op.EndMarkedContent);
 
-//#endregion
-//#region src/objects/pdf-ref.ts
-/**
-* Default cache size for PdfRef interning.
-* Object references tend to be more numerous than names in typical PDFs.
-*/
-const DEFAULT_REF_CACHE_SIZE = 2e4;
-/**
-* PDF indirect reference (interned).
-*
-* In PDF: `1 0 R`, `42 0 R`
-*
-* References are interned using an LRU cache to prevent unbounded memory growth.
-* `PdfRef.of(1, 0) === PdfRef.of(1, 0)` as long as both are in cache.
-* Use `.of()` to get or create instances.
-*/
-var PdfRef = class PdfRef {
-	get type() {
-		return "ref";
-	}
-	static cache = new LRUCache(DEFAULT_REF_CACHE_SIZE);
-	constructor(objectNumber, generation) {
-		this.objectNumber = objectNumber;
-		this.generation = generation;
-	}
-	/**
-	* Get or create an interned PdfRef for the given object/generation pair.
-	*/
-	static of(objectNumber, generation = 0) {
-		const key$1 = `${objectNumber} ${generation}`;
-		let cached = PdfRef.cache.get(key$1);
-		if (!cached) {
-			cached = new PdfRef(objectNumber, generation);
-			PdfRef.cache.set(key$1, cached);
-		}
-		return cached;
-	}
-	/**
-	* Clear the reference cache.
-	*
-	* Useful for long-running applications that process many PDFs
-	* and want to reclaim memory between documents.
-	*/
-	static clearCache() {
-		PdfRef.cache.clear();
-	}
-	/**
-	* Get the current size of the LRU cache.
-	*/
-	static get cacheSize() {
-		return PdfRef.cache.size;
-	}
-	/**
-	* Returns the PDF syntax representation: "1 0 R"
-	*/
-	toString() {
-		return `${this.objectNumber} ${this.generation} R`;
-	}
-	toBytes(writer) {
-		writer.writeAscii(`${this.objectNumber} ${this.generation} R`);
-	}
-};
-
 //#endregion
 //#region src/helpers/colors.ts
 /**
@@ -24321,14 +24327,16 @@ var PDFPage = class PDFPage {
 	/**
 	* Get the page's Resources dictionary.
 	*
-	* Creates an empty one if it doesn't exist.
+	* If Resources is a reference, it's dereferenced.
+	* If Resources doesn't exist or is inherited from a parent,
+	* a new empty dict is created on this page.
 	*/
 	getResources() {
 		let resources = this.dict.get("Resources");
-		if (!(resources instanceof PdfDict)) {
-			resources = new PdfDict();
-			this.dict.set("Resources", resources);
-		}
+		if (resources instanceof PdfRef) resources = this.ctx.resolve(resources) ?? void 0;
+		if (resources instanceof PdfDict) return resources;
+		resources = new PdfDict();
+		this.dict.set("Resources", resources);
 		return resources;
 	}
 	/**
@@ -24458,7 +24466,6 @@ var PDFPage = class PDFPage {
 	* ```
 	*/
 	drawField(field, options) {
-		if (!this.ctx) throw new Error("Cannot draw field on page without context");
 		if (!(field instanceof TerminalField)) throw new Error(`Cannot draw non-terminal field "${field.name}"`);
 		if (field instanceof SignatureField) throw new Error("Signature fields cannot be drawn with drawField. Use form.createSignatureField() which creates the widget automatically.");
 		if (field instanceof RadioField) {
@@ -24543,7 +24550,6 @@ var PDFPage = class PDFPage {
 	* Generate appearance stream for a widget.
 	*/
 	generateWidgetAppearance(field, widget, options) {
-		if (!this.ctx) return;
 		const catalogDict = this.ctx.catalog.getDict();
 		const acroForm = AcroForm.load(catalogDict, this.ctx.registry);
 		if (!acroForm) return;
@@ -25193,7 +25199,6 @@ var PDFPage = class PDFPage {
 	* Add a text markup annotation (internal helper).
 	*/
 	addTextMarkupAnnotation(subtype, options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		let annotDict;
 		switch (subtype) {
 			case "Highlight":
@@ -25242,7 +25247,6 @@ var PDFPage = class PDFPage {
 	* ```
 	*/
 	addLinkAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const destination = options.destination;
 		if (destination) {
 			const destinationPage = destination.page;
@@ -25262,7 +25266,6 @@ var PDFPage = class PDFPage {
 	* @returns The created annotation
 	*/
 	addTextAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const annotDict = PDFTextAnnotation.create(options);
 		const annotRef = this.ctx.register(annotDict);
 		this.addAnnotationRef(annotRef);
@@ -25275,7 +25278,6 @@ var PDFPage = class PDFPage {
 	* @returns The created annotation
 	*/
 	addLineAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const annotDict = PDFLineAnnotation.create(options);
 		const annotRef = this.ctx.register(annotDict);
 		this.addAnnotationRef(annotRef);
@@ -25288,7 +25290,6 @@ var PDFPage = class PDFPage {
 	* @returns The created annotation
 	*/
 	addSquareAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const annotDict = PDFSquareAnnotation.create(options);
 		const annotRef = this.ctx.register(annotDict);
 		this.addAnnotationRef(annotRef);
@@ -25301,7 +25302,6 @@ var PDFPage = class PDFPage {
 	* @returns The created annotation
 	*/
 	addCircleAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const annotDict = PDFCircleAnnotation.create(options);
 		const annotRef = this.ctx.register(annotDict);
 		this.addAnnotationRef(annotRef);
@@ -25314,7 +25314,6 @@ var PDFPage = class PDFPage {
 	* @returns The created annotation
 	*/
 	addStampAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const annotDict = PDFStampAnnotation.create(options);
 		const annotRef = this.ctx.register(annotDict);
 		this.addAnnotationRef(annotRef);
@@ -25327,7 +25326,6 @@ var PDFPage = class PDFPage {
 	* @returns The created annotation
 	*/
 	addInkAnnotation(options) {
-		if (!this.ctx) throw new Error("Cannot add annotation to page without context");
 		const annotDict = PDFInkAnnotation.create(options);
 		const annotRef = this.ctx.register(annotDict);
 		this.addAnnotationRef(annotRef);
@@ -25347,7 +25345,6 @@ var PDFPage = class PDFPage {
 	* ```
 	*/
 	removeAnnotation(annotation) {
-		if (!this.ctx) return;
 		const annots = this.dict.getArray("Annots");
 		if (!annots) return;
 		const removeMatchingEntry = (predicate) => {
@@ -25409,7 +25406,6 @@ var PDFPage = class PDFPage {
 	* ```
 	*/
 	flattenAnnotations(options) {
-		if (!this.ctx) return 0;
 		const count = new AnnotationFlattener(this.ctx.registry).flattenPage(this.dict, options);
 		this.invalidateAnnotationCache();
 		return count;
@@ -25623,7 +25619,6 @@ var PDFPage = class PDFPage {
 			return fontName;
 		}
 		if (font instanceof EmbeddedFont) {
-			if (!this.ctx) throw new Error("Cannot use embedded fonts without document context");
 			const fontRef = this.ctx.getFontRef(font);
 			for (const [existingName, value] of fonts) if (value instanceof PdfRef && value.objectNumber === fontRef.objectNumber && value.generation === fontRef.generation) return existingName.value;
 			const fontName = this.generateUniqueName(fonts, "F");
@@ -25747,7 +25742,6 @@ var PDFPage = class PDFPage {
 	* This method checks the page first, then walks up the Parent chain.
 	*/
 	resolveInheritedResources() {
-		if (!this.ctx) return null;
 		let currentDict = this.dict;
 		while (currentDict) {
 			const resourcesEntry = currentDict.get("Resources");
@@ -25801,7 +25795,6 @@ var PDFPage = class PDFPage {
 			const resolvedRefs = /* @__PURE__ */ new Map();
 			const decodedStreams = /* @__PURE__ */ new Map();
 			const preResolveValue = (value) => {
-				if (!this.ctx) return;
 				if (value instanceof PdfRef) {
 					const key$1 = `${value.objectNumber} ${value.generation} R`;
 					if (resolvedRefs.has(key$1)) return;
@@ -25824,10 +25817,7 @@ var PDFPage = class PDFPage {
 			const pdfFont = parseFont(fontDictEntry, {
 				resolveRef: (ref) => {
 					if (ref instanceof PdfRef && this.ctx) {
-						const key$1 = `${ref.objectNumber} ${ref.generation} R`;
-						const preResolved = resolvedRefs.get(key$1);
-						if (preResolved) return preResolved;
-						const obj = this.ctx.getObject(ref);
+						const obj = this.ctx.resolve(ref);
 						if (obj instanceof PdfDict || obj instanceof PdfArray || obj instanceof PdfStream) return obj;
 					}
 					return null;
@@ -31838,22 +31828,6 @@ function createFileSpec(filename, embeddedFileRef, options = {}) {
 //#endregion
 //#region src/document/name-tree.ts
 /**
-* PDF Name Tree implementation.
-*
-* Name trees are sorted key-value structures used for:
-* - /EmbeddedFiles (attachments)
-* - /Dests (named destinations)
-* - /JavaScript (document-level scripts)
-* - /AP (appearance streams)
-*
-* Structure:
-* - Leaf nodes have /Names: [key1, value1, key2, value2, ...]
-* - Intermediate nodes have /Kids: [ref1, ref2, ...]
-* - Intermediate nodes have /Limits: [minKey, maxKey] for binary search
-*
-* @see PDF 1.7 spec section 7.9.6
-*/
-/**
 * Maximum depth for tree traversal (prevents infinite loops on malformed PDFs).
 */
 const MAX_DEPTH = 10;
@@ -32406,12 +32380,6 @@ var PDFContext = class {
 		return this.registry.resolve(ref);
 	}
 	/**
-	* Get an object by reference (sync, only if already loaded).
-	*/
-	getObject(ref) {
-		return this.registry.getObject(ref);
-	}
-	/**
 	* Get the reference for an object.
 	*/
 	getRef(obj) {