From 7976fc7851a486cc04f2f393ed5e15981366e9ab Mon Sep 17 00:00:00 2001
From: Jonas Jenwald <jonas.jenwald@gmail.com>
Date: Thu, 19 Jan 2023 12:40:09 +0100
Subject: [PATCH] [api-minor] Deprecate calling `getDocument` directly with a
 `PDFDataRangeTransport`-instance

In general it's recommended to pass a *parameter object* when calling the `getDocument`-function in the API, since that's the only way to provide additional options, and the fact that it also accepts a URL or TypedArray directly is now mostly for backwards compatibility reasons.
However, the `getDocument`-function also accepts a direct `PDFDataRangeTransport`-instance which just seems unnecessary.

*Please note:* The `PDFDataRangeTransport`-implementation was added specifically for the *built-in* Firefox PDF Viewer, however it's most likely not commonly used by any third-party (given that it requires manual PDF-data loading).
Furthermore, the default-viewer always provides a *parameter object* when calling the `getDocument`-function and it's thus completely unaffected by these changes.
---
 src/display/api.js    | 12 +++++++++---
 test/unit/api_spec.js |  4 ++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/display/api.js b/src/display/api.js
index a90e8bcd6..b960a16d3 100644
--- a/src/display/api.js
+++ b/src/display/api.js
@@ -233,8 +233,7 @@ if (typeof PDFJSDev === "undefined" || !PDFJSDev.test("PRODUCTION")) {
  */
 
 /**
- * @typedef { string | URL | TypedArray | ArrayBuffer |
- *            PDFDataRangeTransport | DocumentInitParameters
+ * @typedef { string | URL | TypedArray | ArrayBuffer | DocumentInitParameters
  * } GetDocumentParameters
  */
 
@@ -258,7 +257,14 @@ function getDocument(src) {
     source = { url: src };
   } else if (isArrayBuffer(src)) {
     source = { data: src };
-  } else if (src instanceof PDFDataRangeTransport) {
+  } else if (
+    (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) &&
+    src instanceof PDFDataRangeTransport
+  ) {
+    deprecated(
+      "`PDFDataRangeTransport`-instance, " +
+        "please use a parameter object with `range`-property instead."
+    );
     source = { range: src };
   } else {
     if (typeof src !== "object") {
diff --git a/test/unit/api_spec.js b/test/unit/api_spec.js
index 0d373d18f..a6063a364 100644
--- a/test/unit/api_spec.js
+++ b/test/unit/api_spec.js
@@ -3265,7 +3265,7 @@ Caron Broadcasting, Inc., an Ohio corporation (“Lessee”).`)
         });
       };
 
-      const loadingTask = getDocument(transport);
+      const loadingTask = getDocument({ range: transport });
       const pdfDocument = await loadingTask.promise;
       expect(pdfDocument.numPages).toEqual(14);
 
@@ -3310,7 +3310,7 @@ Caron Broadcasting, Inc., an Ohio corporation (“Lessee”).`)
         });
       };
 
-      const loadingTask = getDocument(transport);
+      const loadingTask = getDocument({ range: transport });
       const pdfDocument = await loadingTask.promise;
       expect(pdfDocument.numPages).toEqual(14);