Improve the API unit-tests, and try to expose more API-functionality in the TypeScript definitions

src/display/api.js

@@ -3361,9 +3361,11 @@ export {
   getDocument,
   LoopbackPort,
   PDFDataRangeTransport,
+  PDFDocumentLoadingTask,
   PDFDocumentProxy,
   PDFPageProxy,
   PDFWorker,
+  RenderTask,
   setPDFNetworkStreamFactory,
   version,
 };

src/pdf.js

@@ -14,6 +14,12 @@
  */
 /* eslint-disable sort-exports/sort-exports */
 
+// eslint-disable-next-line max-len
+/** @typedef {import("./display/api").PDFDocumentLoadingTask} PDFDocumentLoadingTask */
+/** @typedef {import("./display/api").PDFDocumentProxy} PDFDocumentProxy */
+/** @typedef {import("./display/api").PDFPageProxy} PDFPageProxy */
+/** @typedef {import("./display/api").RenderTask} RenderTask */
+
 import {
   addLinkAttributes,
   getFilenameFromUrl,

test/unit/api_spec.js

@@ -35,9 +35,11 @@ import {
   DefaultCanvasFactory,
   getDocument,
   PDFDataRangeTransport,
+  PDFDocumentLoadingTask,
   PDFDocumentProxy,
   PDFPageProxy,
   PDFWorker,
+  RenderTask,
 } from "../../src/display/api.js";
 import {
   RenderingCancelledException,
@@ -75,6 +77,7 @@ describe("api", function () {
     it("creates pdf doc from URL-string", async function () {
       const urlStr = TEST_PDFS_PATH + basicApiFileName;
       const loadingTask = getDocument(urlStr);
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
       const pdfDocument = await loadingTask.promise;
 
       expect(typeof urlStr).toEqual("string");
@@ -93,6 +96,7 @@ describe("api", function () {
         window.location
       );
       const loadingTask = getDocument(urlObj);
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
       const pdfDocument = await loadingTask.promise;
 
       expect(urlObj instanceof URL).toEqual(true);
@@ -104,6 +108,7 @@ describe("api", function () {
 
     it("creates pdf doc from URL", async function () {
       const loadingTask = getDocument(basicApiGetDocumentParams);
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
 
       const progressReportedCapability = createPromiseCapability();
       // Attach the callback that is used to report loading progress;
@@ -128,6 +133,7 @@ describe("api", function () {
 
     it("creates pdf doc from URL and aborts before worker initialized", async function () {
       const loadingTask = getDocument(basicApiGetDocumentParams);
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
       const destroyed = loadingTask.destroy();
 
       try {
@@ -143,6 +149,7 @@ describe("api", function () {
 
     it("creates pdf doc from URL and aborts loading after worker initialized", async function () {
       const loadingTask = getDocument(basicApiGetDocumentParams);
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
       // This can be somewhat random -- we cannot guarantee perfect
       // 'Terminate' message to the worker before/after setting up pdfManager.
       const destroyed = loadingTask._worker.promise.then(function () {
@@ -162,6 +169,7 @@ describe("api", function () {
       expect(typedArrayPdf.length).toEqual(basicApiFileLength);
 
       const loadingTask = getDocument(typedArrayPdf);
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
 
       const progressReportedCapability = createPromiseCapability();
       loadingTask.onProgress = function (data) {
@@ -181,6 +189,7 @@ describe("api", function () {
     it("creates pdf doc from invalid PDF file", async function () {
       // A severely corrupt PDF file (even Adobe Reader fails to open it).
       const loadingTask = getDocument(buildGetDocumentParams("bug1020226.pdf"));
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
 
       try {
         await loadingTask.promise;
@@ -203,6 +212,7 @@ describe("api", function () {
       const loadingTask = getDocument(
         buildGetDocumentParams("non-existent.pdf")
       );
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
 
       try {
         await loadingTask.promise;
@@ -218,6 +228,7 @@ describe("api", function () {
 
     it("creates pdf doc from PDF file protected with user and owner password", async function () {
       const loadingTask = getDocument(buildGetDocumentParams("pr6531_1.pdf"));
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
 
       const passwordNeededCapability = createPromiseCapability();
       const passwordIncorrectCapability = createPromiseCapability();
@@ -264,6 +275,10 @@ describe("api", function () {
           password: "",
         })
       );
+      expect(
+        passwordNeededLoadingTask instanceof PDFDocumentLoadingTask
+      ).toEqual(true);
+
       const result1 = passwordNeededLoadingTask.promise.then(
         function () {
           // Shouldn't get here.
@@ -282,6 +297,10 @@ describe("api", function () {
           password: "qwerty",
         })
       );
+      expect(
+        passwordIncorrectLoadingTask instanceof PDFDocumentLoadingTask
+      ).toEqual(true);
+
       const result2 = passwordIncorrectLoadingTask.promise.then(
         function () {
           // Shouldn't get here.
@@ -300,6 +319,10 @@ describe("api", function () {
           password: "asdfasdf",
         })
       );
+      expect(
+        passwordAcceptedLoadingTask instanceof PDFDocumentLoadingTask
+      ).toEqual(true);
+
       const result3 = passwordAcceptedLoadingTask.promise.then(function (data) {
         expect(data instanceof PDFDocumentProxy).toEqual(true);
         return passwordAcceptedLoadingTask.destroy();
@@ -317,11 +340,18 @@ describe("api", function () {
         const passwordNeededLoadingTask = getDocument(
           buildGetDocumentParams(filename)
         );
+        expect(
+          passwordNeededLoadingTask instanceof PDFDocumentLoadingTask
+        ).toEqual(true);
+
         const passwordIncorrectLoadingTask = getDocument(
           buildGetDocumentParams(filename, {
             password: "qwerty",
           })
         );
+        expect(
+          passwordIncorrectLoadingTask instanceof PDFDocumentLoadingTask
+        ).toEqual(true);
 
         let passwordNeededDestroyed;
         passwordNeededLoadingTask.onPassword = function (callback, reason) {
@@ -371,6 +401,7 @@ describe("api", function () {
 
     it("creates pdf doc from empty typed array", async function () {
       const loadingTask = getDocument(new Uint8Array(0));
+      expect(loadingTask instanceof PDFDocumentLoadingTask).toEqual(true);
 
       try {
         await loadingTask.promise;
@@ -389,10 +420,12 @@ describe("api", function () {
 
     it("checks that `docId`s are unique and increasing", async function () {
       const loadingTask1 = getDocument(basicApiGetDocumentParams);
+      expect(loadingTask1 instanceof PDFDocumentLoadingTask).toEqual(true);
       await loadingTask1.promise;
       const docId1 = loadingTask1.docId;
 
       const loadingTask2 = getDocument(basicApiGetDocumentParams);
+      expect(loadingTask2 instanceof PDFDocumentLoadingTask).toEqual(true);
       await loadingTask2.promise;
       const docId2 = loadingTask2.docId;
 
@@ -1842,11 +1875,14 @@ describe("api", function () {
         viewport.width,
         viewport.height
       );
+
       const renderTask = pdfPage.render({
         canvasContext: canvasAndCtx.context,
         canvasFactory: CanvasFactory,
         viewport,
       });
+      expect(renderTask instanceof RenderTask).toEqual(true);
+
       await renderTask.promise;
       const stats = pdfPage.stats;
 
@@ -1879,6 +1915,8 @@ describe("api", function () {
         canvasFactory: CanvasFactory,
         viewport,
       });
+      expect(renderTask instanceof RenderTask).toEqual(true);
+
       renderTask.cancel();
 
       try {
@@ -1907,6 +1945,8 @@ describe("api", function () {
         canvasFactory: CanvasFactory,
         viewport,
       });
+      expect(renderTask instanceof RenderTask).toEqual(true);
+
       renderTask.cancel();
 
       try {
@@ -1923,6 +1963,8 @@ describe("api", function () {
         canvasFactory: CanvasFactory,
         viewport,
       });
+      expect(reRenderTask instanceof RenderTask).toEqual(true);
+
       await reRenderTask.promise;
 
       CanvasFactory.destroy(canvasAndCtx);
@@ -1944,12 +1986,15 @@ describe("api", function () {
         viewport,
         optionalContentConfigPromise,
       });
+      expect(renderTask1 instanceof RenderTask).toEqual(true);
+
       const renderTask2 = page.render({
         canvasContext: canvasAndCtx.context,
         canvasFactory: CanvasFactory,
         viewport,
         optionalContentConfigPromise,
       });
+      expect(renderTask2 instanceof RenderTask).toEqual(true);
 
       await Promise.all([
         renderTask1.promise,
@@ -1982,8 +2027,9 @@ describe("api", function () {
         canvasFactory: CanvasFactory,
         viewport,
       });
-      await renderTask.promise;
+      expect(renderTask instanceof RenderTask).toEqual(true);
 
+      await renderTask.promise;
       await pdfDoc.cleanup();
 
       expect(true).toEqual(true);
@@ -2010,6 +2056,8 @@ describe("api", function () {
         canvasFactory: CanvasFactory,
         viewport,
       });
+      expect(renderTask instanceof RenderTask).toEqual(true);
+
       // Ensure that clean-up runs during rendering.
       renderTask.onContinue = function (cont) {
         waitSome(cont);