@libpdf/core 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -98,8 +98,9 @@ declare class PdfArray implements PdfPrimitive {
   get length(): number;
   /**
    * Get item at index. Returns undefined if out of bounds.
+   * If resolver is provided, resolves indirect references.
    */
-  at(index: number): PdfObject | undefined;
+  at(index: number, resolver?: RefResolver): PdfObject | undefined;
   /**
    * Set item at index. Extends array if needed.
    */
@@ -332,7 +333,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 +355,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 +523,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 +613,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 +646,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 +4511,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 +4521,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 +4628,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 +4759,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 +4887,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 +4961,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;
   /**
@@ -8096,14 +8097,6 @@ declare class PDF {
    * Returns null if index out of bounds.
    */
   getPage(index: number): PDFPage | null;
-  /**
-   * Ensure page resources are resolved (not a reference).
-   *
-   * Pages may have Resources as a PdfRef pointing to a shared resources dict.
-   * The sync getResources() method on PDFPage needs the actual dict, not a ref.
-   * This resolves the reference and replaces it in the page dict.
-   */
-  private ensurePageResourcesResolved;
   /**
    * Add a new blank page.
    *
@@ -9261,11 +9254,11 @@ declare function createAnnotation(dict: PdfDict, ref: PdfRef | null, registry: O
 /**
  * Check if an annotation is a Widget (form field).
  */
-declare function isWidgetAnnotation(dict: PdfDict): boolean;
+declare function isWidgetAnnotation(dict: PdfDict, registry?: ObjectRegistry): boolean;
 /**
  * Check if an annotation is a Popup.
  */
-declare function isPopupAnnotation(dict: PdfDict): boolean;
+declare function isPopupAnnotation(dict: PdfDict, registry?: ObjectRegistry): boolean;
 //#endregion
 export { AnnotationFlags, type AnnotationSubtype, type AuthenticationResult, type BorderStyle, type BorderStyleType, type ButtonField, type CMYK, type CaretAnnotationOptions, type CaretSymbol, CertificateChainError, type CheckboxField, type CheckboxOptions, type CheckboxSymbol, type CircleAnnotationOptions, type Color, type CopyPagesOptions, CryptoKeySigner, type Degrees, type DestinationType, type DigestAlgorithm, type DocumentMetadata, type DrawCircleOptions, type DrawEllipseOptions, type DrawFieldOptions, type DrawImageOptions, type DrawLineOptions, type DrawPageOptions, type DrawRectangleOptions, type DrawTextOptions, type DropdownField, type DropdownOptions, type EmbedFontOptions, type EmbeddedFont, type EncryptionAlgorithmOption, type ExtractPagesOptions, type FieldOptions, type FieldType, type FieldValue, type FileAttachmentIcon, type FlattenAllOptions, type FlattenAllResult, type FlattenAnnotationsOptions, type FlattenLayersResult, type FlattenOptions, type FontInput, type FormField, type FormProperties, type FreeTextAnnotationOptions, type FreeTextJustification, GoogleKmsSigner, type Grayscale, type HighlightMode, HttpTimestampAuthority, type HttpTimestampAuthorityOptions, type InkAnnotationOptions, type KeyType, KmsSignerError, type LayerInfo, type LayoutResult, type LineAnnotationOptions, type LineCap, type LineEndingStyle, type LineJoin, type LinkAction, type LinkAnnotationOptions, type LinkDestination, type ListBoxField, type ListboxOptions, type LoadOptions, type MergeOptions, P12Signer, type PAdESLevel, PDF, PDFAnnotation, PDFCaretAnnotation, PDFCircleAnnotation, PDFEmbeddedPage, PDFFileAttachmentAnnotation, PDFForm, PDFFreeTextAnnotation, PDFHighlightAnnotation, PDFImage, PDFInkAnnotation, PDFLineAnnotation, PDFLinkAnnotation, PDFMarkupAnnotation, PDFPage, PDFPolygonAnnotation, PDFPolylineAnnotation, PDFPopupAnnotation, PDFSquareAnnotation, PDFSquigglyAnnotation, PDFStampAnnotation, PDFStrikeOutAnnotation, PDFTextAnnotation, PDFTextMarkupAnnotation, PDFUnderlineAnnotation, PDFUnknownAnnotation, PathBuilder, type PathOptions, PdfArray, PdfBool, PdfDict, PdfName, PdfNull, PdfNumber, type PdfObject, PdfRef, PdfStream, PdfString, type PemBlock, PermissionDeniedError, type PermissionOptions, type Permissions, PlaceholderError, type Point, type PolygonAnnotationOptions, type PolylineAnnotationOptions, type PopupOptions, type PositionedWord, type ProtectionOptions, type RGB, type RadioField, type RadioGroupOptions, type RadioSymbol, type Rect, type Rectangle, type RemoveAnnotationsOptions, RevocationError, type RevocationProvider, type Rotation, type RotationOrigin, type RotationOriginName, STANDARD_STAMPS, type SaveOptions, SecurityError, type SecurityInfo, type SetTitleOptions, type SignOptions, type SignResult, type SignWarning, type SignatureAlgorithm, SignatureError, type SignatureField, type SignatureFieldOptions, type Signer, SignerError, type SquareAnnotationOptions, type StampAnnotationOptions, type StampName, Standard14Font, type Standard14FontName, StandardFonts, type SubFilter, type TextAlignment, type TextAnnotationIcon, type TextAnnotationOptions, type TextAnnotationState, type TextAnnotationStateModel, type TextField, type TextFieldOptions, type TextLine, type TextMarkupAnnotationOptions, type TimestampAuthority, TimestampError, type TrappedStatus, black, blue, cmyk, createAnnotation, degrees, grayscale, green, isPopupAnnotation, isWidgetAnnotation, layoutJustifiedLine, layoutText, lineCapToNumber, lineJoinToNumber, measureText, parsePem, rectToQuadPoints, rectsToQuadPoints, red, rgb, version, white };
 //# sourceMappingURL=index.d.mts.map