Add optional onWarning handler

Currently `pdf-lib` uses `console.warn()` to alert about various issues.

Here we add an optional `onWarning` parameter that can be passed to the
document or parser to provide an alternative mechanism for handling
these alerts.

Author: davecardwell

src/api/PDFDocument.ts

@@ -48,7 +48,7 @@ import {
 import PDFObject from 'src/core/objects/PDFObject';
 import PDFRef from 'src/core/objects/PDFRef';
 import { Fontkit } from 'src/types/fontkit';
-import { TransformationMatrix } from 'src/types/matrix';
+import { OnWarningHandler, TransformationMatrix } from 'src/types';
 import {
   assertIs,
   assertIsOneOfOrUndefined,
@@ -131,6 +131,7 @@ export default class PDFDocument {
       ignoreEncryption = false,
       parseSpeed = ParseSpeeds.Slow,
       throwOnInvalidObject = false,
+      onWarning,
       updateMetadata = true,
       capNumbers = false,
     } = options;
@@ -146,24 +147,30 @@ export default class PDFDocument {
       parseSpeed,
       throwOnInvalidObject,
       capNumbers,
+      onWarning,
     ).parseDocument();
-    return new PDFDocument(context, ignoreEncryption, updateMetadata);
+    return new PDFDocument(
+      context,
+      ignoreEncryption,
+      updateMetadata,
+      onWarning,
+    );
   }
 
   /**
    * Create a new [[PDFDocument]].
    * @returns Resolves with the newly created document.
    */
   static async create(options: CreateOptions = {}) {
-    const { updateMetadata = true } = options;
+    const { updateMetadata = true, onWarning } = options;
 
     const context = PDFContext.create();
     const pageTree = PDFPageTree.withContext(context);
     const pageTreeRef = context.register(pageTree);
     const catalog = PDFCatalog.withContextAndPages(context, pageTreeRef);
     context.trailerInfo.Root = context.register(catalog);
 
-    return new PDFDocument(context, false, updateMetadata);
+    return new PDFDocument(context, false, updateMetadata, onWarning);
   }
 
   /** The low-level context of this document. */
@@ -175,6 +182,9 @@ export default class PDFDocument {
   /** Whether or not this document is encrypted. */
   readonly isEncrypted: boolean;
 
+  /** The function called with details of non-fatal issues. */
+  readonly onWarning: OnWarningHandler;
+
   /** The default word breaks used in PDFPage.drawText */
   defaultWordBreaks: string[] = [' '];
 
@@ -193,13 +203,16 @@ export default class PDFDocument {
     context: PDFContext,
     ignoreEncryption: boolean,
     updateMetadata: boolean,
+    onWarning: OnWarningHandler = console.warn.bind(console),
   ) {
     assertIs(context, 'context', [[PDFContext, 'PDFContext']]);
     assertIs(ignoreEncryption, 'ignoreEncryption', ['boolean']);
+    assertIs(onWarning, 'onWarning', ['function']);
 
     this.context = context;
     this.catalog = context.lookup(context.trailerInfo.Root) as PDFCatalog;
     this.isEncrypted = !!context.lookup(context.trailerInfo.Encrypt);
+    this.onWarning = onWarning;
 
     this.pageCache = Cache.populatedBy(this.computePages);
     this.pageMap = new Map();
@@ -254,7 +267,7 @@ export default class PDFDocument {
   getForm(): PDFForm {
     const form = this.formCache.access();
     if (form.hasXFA()) {
-      console.warn(
+      this.onWarning(
         'Removing XFA form data as pdf-lib does not support reading or writing XFA',
       );
       form.deleteXFA();

src/api/PDFDocumentOptions.ts

@@ -1,5 +1,5 @@
 import { EmbeddedFileOptions } from 'src/core/embedders/FileEmbedder';
-import { TypeFeatures } from 'src/types/fontkit';
+import { OnWarningHandler, TypeFeatures } from 'src/types';
 
 export enum ParseSpeeds {
   Fastest = Infinity,
@@ -25,11 +25,13 @@ export interface LoadOptions {
   ignoreEncryption?: boolean;
   parseSpeed?: ParseSpeeds | number;
   throwOnInvalidObject?: boolean;
+  onWarning?: OnWarningHandler;
   updateMetadata?: boolean;
   capNumbers?: boolean;
 }
 
 export interface CreateOptions {
+  onWarning?: OnWarningHandler;
   updateMetadata?: boolean;
 }
 

src/api/form/PDFTextField.ts

@@ -607,7 +607,7 @@ export default class PDFTextField extends PDFField {
   enableCombing() {
     if (this.getMaxLength() === undefined) {
       const msg = `PDFTextFields must have a max length in order to be combed`;
-      console.warn(msg);
+      this.doc.onWarning(msg);
     }
 
     this.markAsDirty();

src/core/parser/BaseParser.ts

@@ -3,6 +3,7 @@ import ByteStream from 'src/core/parser/ByteStream';
 import CharCodes from 'src/core/syntax/CharCodes';
 import { IsDigit, IsNumeric } from 'src/core/syntax/Numeric';
 import { IsWhitespace } from 'src/core/syntax/Whitespace';
+import { OnWarningHandler } from 'src/types';
 import { charFromCode } from 'src/utils';
 
 const { Newline, CarriageReturn } = CharCodes;
@@ -11,10 +12,16 @@ const { Newline, CarriageReturn } = CharCodes;
 class BaseParser {
   protected readonly bytes: ByteStream;
   protected readonly capNumbers: boolean;
+  protected readonly onWarning: OnWarningHandler;
 
-  constructor(bytes: ByteStream, capNumbers = false) {
+  constructor(
+    bytes: ByteStream,
+    capNumbers = false,
+    onWarning = console.warn.bind(console),
+  ) {
     this.bytes = bytes;
     this.capNumbers = capNumbers;
+    this.onWarning = onWarning;
   }
 
   protected parseRawInt(): number {
@@ -64,11 +71,11 @@ class BaseParser {
     if (numberValue > Number.MAX_SAFE_INTEGER) {
       if (this.capNumbers) {
         const msg = `Parsed number that is too large for some PDF readers: ${value}, using Number.MAX_SAFE_INTEGER instead.`;
-        console.warn(msg);
+        this.onWarning(msg);
         return Number.MAX_SAFE_INTEGER;
       } else {
         const msg = `Parsed number that is too large for some PDF readers: ${value}, not capping.`;
-        console.warn(msg);
+        this.onWarning(msg);
       }
     }
 

src/core/parser/PDFObjectParser.ts

@@ -27,6 +27,7 @@ import { IsDelimiter } from 'src/core/syntax/Delimiters';
 import { Keywords } from 'src/core/syntax/Keywords';
 import { IsDigit, IsNumeric } from 'src/core/syntax/Numeric';
 import { IsWhitespace } from 'src/core/syntax/Whitespace';
+import { OnWarningHandler } from 'src/types';
 import { charFromCode } from 'src/utils';
 
 // TODO: Throw error if eof is reached before finishing object parse...
@@ -35,18 +36,26 @@ class PDFObjectParser extends BaseParser {
     bytes: Uint8Array,
     context: PDFContext,
     capNumbers?: boolean,
-  ) => new PDFObjectParser(ByteStream.of(bytes), context, capNumbers);
+    onWarning?: OnWarningHandler,
+  ) =>
+    new PDFObjectParser(ByteStream.of(bytes), context, capNumbers, onWarning);
 
   static forByteStream = (
     byteStream: ByteStream,
     context: PDFContext,
     capNumbers = false,
-  ) => new PDFObjectParser(byteStream, context, capNumbers);
+    onWarning?: OnWarningHandler,
+  ) => new PDFObjectParser(byteStream, context, capNumbers, onWarning);
 
   protected readonly context: PDFContext;
 
-  constructor(byteStream: ByteStream, context: PDFContext, capNumbers = false) {
-    super(byteStream, capNumbers);
+  constructor(
+    byteStream: ByteStream,
+    context: PDFContext,
+    capNumbers = false,
+    onWarning?: OnWarningHandler,
+  ) {
+    super(byteStream, capNumbers, onWarning);
     this.context = context;
   }
 

src/core/parser/PDFObjectStreamParser.ts

@@ -5,21 +5,32 @@ import PDFRawStream from 'src/core/objects/PDFRawStream';
 import PDFRef from 'src/core/objects/PDFRef';
 import ByteStream from 'src/core/parser/ByteStream';
 import PDFObjectParser from 'src/core/parser/PDFObjectParser';
+import { OnWarningHandler } from 'src/types';
 import { waitForTick } from 'src/utils';
 
 class PDFObjectStreamParser extends PDFObjectParser {
   static forStream = (
     rawStream: PDFRawStream,
     shouldWaitForTick?: () => boolean,
-  ) => new PDFObjectStreamParser(rawStream, shouldWaitForTick);
+    onWarning?: OnWarningHandler,
+  ) => new PDFObjectStreamParser(rawStream, shouldWaitForTick, onWarning);
 
   private alreadyParsed: boolean;
   private readonly shouldWaitForTick: () => boolean;
   private readonly firstOffset: number;
   private readonly objectCount: number;
 
-  constructor(rawStream: PDFRawStream, shouldWaitForTick?: () => boolean) {
-    super(ByteStream.fromPDFRawStream(rawStream), rawStream.dict.context);
+  constructor(
+    rawStream: PDFRawStream,
+    shouldWaitForTick?: () => boolean,
+    onWarning?: OnWarningHandler,
+  ) {
+    super(
+      ByteStream.fromPDFRawStream(rawStream),
+      rawStream.dict.context,
+      undefined,
+      onWarning,
+    );
 
     const { dict } = rawStream;
 

src/core/parser/PDFParser.ts

@@ -22,6 +22,7 @@ import PDFContext from 'src/core/PDFContext';
 import CharCodes from 'src/core/syntax/CharCodes';
 import { Keywords } from 'src/core/syntax/Keywords';
 import { IsDigit } from 'src/core/syntax/Numeric';
+import { OnWarningHandler } from 'src/types';
 import { waitForTick } from 'src/utils';
 
 class PDFParser extends PDFObjectParser {
@@ -30,8 +31,15 @@ class PDFParser extends PDFObjectParser {
     objectsPerTick?: number,
     throwOnInvalidObject?: boolean,
     capNumbers?: boolean,
+    onWarning?: OnWarningHandler,
   ) =>
-    new PDFParser(pdfBytes, objectsPerTick, throwOnInvalidObject, capNumbers);
+    new PDFParser(
+      pdfBytes,
+      objectsPerTick,
+      throwOnInvalidObject,
+      capNumbers,
+      onWarning,
+    );
 
   private readonly objectsPerTick: number;
   private readonly throwOnInvalidObject: boolean;
@@ -43,8 +51,9 @@ class PDFParser extends PDFObjectParser {
     objectsPerTick = Infinity,
     throwOnInvalidObject = false,
     capNumbers = false,
+    onWarning?: OnWarningHandler,
   ) {
-    super(ByteStream.of(pdfBytes), PDFContext.create(), capNumbers);
+    super(ByteStream.of(pdfBytes), PDFContext.create(), capNumbers, onWarning);
     this.objectsPerTick = objectsPerTick;
     this.throwOnInvalidObject = throwOnInvalidObject;
   }
@@ -70,7 +79,7 @@ class PDFParser extends PDFObjectParser {
     this.maybeRecoverRoot();
 
     if (this.context.lookup(PDFRef.of(0))) {
-      console.warn('Removing parsed object: 0 0 R');
+      this.onWarning('Removing parsed object: 0 0 R');
       this.context.delete(PDFRef.of(0));
     }
 
@@ -182,11 +191,11 @@ class PDFParser extends PDFObjectParser {
 
     const msg = `Trying to parse invalid object: ${JSON.stringify(startPos)})`;
     if (this.throwOnInvalidObject) throw new Error(msg);
-    console.warn(msg);
+    this.onWarning(msg);
 
     const ref = this.parseIndirectObjectHeader();
 
-    console.warn(`Invalid object ref: ${ref}`);
+    this.onWarning(`Invalid object ref: ${ref}`);
 
     this.skipWhitespaceAndComments();
     const start = this.bytes.offset();

src/types/index.ts

@@ -1 +1,4 @@
-export { TransformationMatrix } from 'src/types/matrix';
+export * from 'src/types/fontkit';
+export * from 'src/types/matrix';
+
+export type OnWarningHandler = (message: string) => void;

src/utils/validators.ts

@@ -94,6 +94,7 @@ export type TypeDescriptor =
   | 'boolean'
   | 'symbol'
   | 'bigint'
+  | 'function'
   | DateConstructor
   | ArrayConstructor
   | Uint8ArrayConstructor
@@ -109,6 +110,7 @@ export const isType = (value: any, type: TypeDescriptor) => {
   if (type === 'boolean') return typeof value === 'boolean';
   if (type === 'symbol') return typeof value === 'symbol';
   if (type === 'bigint') return typeof value === 'bigint';
+  if (type === 'function') return typeof value === 'function';
   if (type === Date) return value instanceof Date;
   if (type === Array) return value instanceof Array;
   if (type === Uint8Array) return value instanceof Uint8Array;

tests/api/PDFDocument.spec.ts

@@ -142,6 +142,20 @@ describe(`PDFDocument`, () => {
         }),
       ).rejects.toEqual(expectedError);
     });
+
+    it(`uses the provided onWarning callback`, async () => {
+      expect.assertions(2);
+      const onWarning = jest.fn();
+      await PDFDocument.load(invalidObjectsPdfBytes, {
+        ignoreEncryption: true,
+        parseSpeed: ParseSpeeds.Fastest,
+        onWarning,
+      });
+      expect(onWarning).toHaveBeenCalledTimes(2);
+      expect(onWarning).toHaveBeenCalledWith(
+        'Trying to parse invalid object: {"line":20,"column":13,"offset":126})',
+      );
+    });
   });
 
   describe(`embedFont() method`, () => {

tests/core/parser/PDFParser.spec.ts

@@ -395,4 +395,29 @@ describe(`PDFParser`, () => {
     const object2 = context.lookup(PDFRef.of(2));
     expect(object2).toBeInstanceOf(PDFString);
   });
+
+  it(`uses the provided onWarning callback`, async () => {
+    expect.assertions(3);
+    const onWarning = jest.fn();
+
+    const input = `
+    %PDF-1.7
+    22 0 obj <</Type/Outlines/First ## 0 R/Last ** 0 R/Count 2>> endobj
+  `;
+    const parser = PDFParser.forBytesWithOptions(
+      typedArrayFor(input),
+      undefined,
+      undefined,
+      undefined,
+      onWarning,
+    );
+    await parser.parseDocument();
+
+    expect(onWarning).toHaveBeenCalledTimes(2);
+    expect(onWarning).toHaveBeenNthCalledWith(
+      1,
+      'Trying to parse invalid object: {"line":3,"column":53,"offset":18})',
+    );
+    expect(onWarning).toHaveBeenNthCalledWith(2, 'Invalid object ref: 22 0 R');
+  });
 });