Re-name and re-factor the PDFLinkService.navigateTo method

This modernizes and improves the code, by using `async`/`await` and by extracting the helper function to its own method.
To hopefully avoid confusion, given the next patch, the method is also re-named to `goToDestination` to make is slightly clearer what it actually does.

src/display/annotation_layer.js

@@ -344,7 +344,7 @@ class LinkAnnotationElement extends AnnotationElement {
     link.href = this.linkService.getDestinationHash(destination);
     link.onclick = () => {
       if (destination) {
-        this.linkService.navigateTo(destination);
+        this.linkService.goToDestination(destination);
       }
       return false;
     };

web/interfaces.js

@@ -54,9 +54,9 @@ class IPDFLinkService {
   set externalLinkEnabled(value) {}
 
   /**
-   * @param dest - The PDF destination object.
+   * @param {string|Array} dest - The named, or explicit, PDF destination.
    */
-  navigateTo(dest) {}
+  async goToDestination(dest) {}
 
   /**
    * @param dest - The PDF destination object.

web/pdf_history.js

@@ -647,7 +647,7 @@ class PDFHistory {
       this.linkService.rotation = destination.rotation;
     }
     if (destination.dest) {
-      this.linkService.navigateTo(destination.dest);
+      this.linkService.goToDestination(destination.dest);
     } else if (destination.hash) {
       this.linkService.setHash(destination.hash);
     } else if (destination.page) {
@@ -655,7 +655,7 @@ class PDFHistory {
       this.linkService.page = destination.page;
     }
 
-    // Since `PDFLinkService.navigateTo` is asynchronous, we thus defer the
+    // Since `PDFLinkService.goToDestination` is asynchronous, we thus defer the
     // resetting of `this._popStateInProgress` slightly.
     Promise.resolve().then(() => {
       this._popStateInProgress = false;

web/pdf_link_service.js

@@ -108,10 +108,19 @@ class PDFLinkService {
   }
 
   /**
-   * @param {string|Array} dest - The named, or explicit, PDF destination.
+   * @deprecated
    */
   navigateTo(dest) {
-    const goToDestination = ({ namedDest, explicitDest }) => {
+    console.error(
+      "Deprecated method: `navigateTo`, use `goToDestination` instead."
+    );
+    this.goToDestination(dest);
+  }
+
+  /**
+   * @private
+   */
+  _goToDestinationHelper(rawDest, namedDest = null, explicitDest) {
     // Dest array looks like that: <page-ref> </XYZ|/FitXXX> <args..>
     const destRef = explicitDest[0];
     let pageNumber;
@@ -126,12 +135,12 @@ class PDFLinkService {
           .getPageIndex(destRef)
           .then(pageIndex => {
             this.cachePageRef(pageIndex + 1, destRef);
-              goToDestination({ namedDest, explicitDest });
+            this._goToDestinationHelper(rawDest, namedDest, explicitDest);
           })
           .catch(() => {
             console.error(
-                `PDFLinkService.navigateTo: "${destRef}" is not ` +
+              `PDFLinkService._goToDestinationHelper: "${destRef}" is not ` +
-                  `a valid page reference, for dest="${dest}".`
+                `a valid page reference, for dest="${rawDest}".`
             );
           });
         return;
@@ -140,15 +149,15 @@ class PDFLinkService {
       pageNumber = destRef + 1;
     } else {
       console.error(
-          `PDFLinkService.navigateTo: "${destRef}" is not ` +
+        `PDFLinkService._goToDestinationHelper: "${destRef}" is not ` +
-            `a valid destination reference, for dest="${dest}".`
+          `a valid destination reference, for dest="${rawDest}".`
       );
       return;
     }
     if (!pageNumber || pageNumber < 1 || pageNumber > this.pagesCount) {
       console.error(
-          `PDFLinkService.navigateTo: "${pageNumber}" is not ` +
+        `PDFLinkService._goToDestinationHelper: "${pageNumber}" is not ` +
-            `a valid page number, for dest="${dest}".`
+          `a valid page number, for dest="${rawDest}".`
       );
       return;
     }
@@ -165,32 +174,30 @@ class PDFLinkService {
       destArray: explicitDest,
       ignoreDestinationZoom: this._ignoreDestinationZoom,
     });
-    };
-
-    new Promise((resolve, reject) => {
-      if (typeof dest === "string") {
-        this.pdfDocument.getDestination(dest).then(destArray => {
-          resolve({
-            namedDest: dest,
-            explicitDest: destArray,
-          });
-        });
-        return;
   }
-      resolve({
+
-        namedDest: "",
+  /**
-        explicitDest: dest,
+   * This method will, when available, also update the browser history.
-      });
+   *
-    }).then(data => {
+   * @param {string|Array} dest - The named, or explicit, PDF destination.
-      if (!Array.isArray(data.explicitDest)) {
+   */
+  async goToDestination(dest) {
+    let namedDest, explicitDest;
+    if (typeof dest === "string") {
+      namedDest = dest;
+      explicitDest = await this.pdfDocument.getDestination(dest);
+    } else {
+      namedDest = null;
+      explicitDest = await dest;
+    }
+    if (!Array.isArray(explicitDest)) {
       console.error(
-          `PDFLinkService.navigateTo: "${data.explicitDest}" is` +
+        `PDFLinkService.goToDestination: "${explicitDest}" is not ` +
-            ` not a valid destination array, for dest="${dest}".`
+          `a valid destination array, for dest="${dest}".`
       );
       return;
     }
-      goToDestination(data);
+    this._goToDestinationHelper(dest, namedDest, explicitDest);
-    });
   }
 
   /**
@@ -307,7 +314,7 @@ class PDFLinkService {
       // Ensure that this parameter is *always* handled last, in order to
       // guarantee that it won't be overridden (e.g. by the "page" parameter).
       if ("nameddest" in params) {
-        this.navigateTo(params.nameddest);
+        this.goToDestination(params.nameddest);
       }
     } else {
       // Named (or explicit) destination.
@@ -323,7 +330,7 @@ class PDFLinkService {
       } catch (ex) {}
 
       if (typeof dest === "string" || isValidExplicitDestination(dest)) {
-        this.navigateTo(dest);
+        this.goToDestination(dest);
         return;
       }
       console.error(
@@ -394,6 +401,9 @@ class PDFLinkService {
     this._pagesRefCache[refStr] = pageNum;
   }
 
+  /**
+   * @private
+   */
   _cachedPageNumber(pageRef) {
     const refStr =
       pageRef.gen === 0 ? `${pageRef.num}R` : `${pageRef.num}R${pageRef.gen}`;
@@ -510,9 +520,9 @@ class SimpleLinkService {
   set rotation(value) {}
 
   /**
-   * @param dest - The PDF destination object.
+   * @param {string|Array} dest - The named, or explicit, PDF destination.
    */
-  navigateTo(dest) {}
+  async goToDestination(dest) {}
 
   /**
    * @param dest - The PDF destination object.

web/pdf_outline_viewer.js

@@ -73,7 +73,7 @@ class PDFOutlineViewer extends BaseTreeViewer {
     element.href = linkService.getDestinationHash(dest);
     element.onclick = () => {
       if (dest) {
-        linkService.navigateTo(dest);
+        linkService.goToDestination(dest);
       }
       return false;
     };