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,91 +108,98 @@ class PDFLinkService {
   }
 
   /**
-   * @param {string|Array} dest - The named, or explicit, PDF destination.
+   * @deprecated
    */
   navigateTo(dest) {
-    const goToDestination = ({ namedDest, explicitDest }) => {
+    console.error(
-      // Dest array looks like that: <page-ref> </XYZ|/FitXXX> <args..>
+      "Deprecated method: `navigateTo`, use `goToDestination` instead."
-      const destRef = explicitDest[0];
+    );
-      let pageNumber;
+    this.goToDestination(dest);
+  }
 
-      if (destRef instanceof Object) {
+  /**
-        pageNumber = this._cachedPageNumber(destRef);
+   * @private
+   */
+  _goToDestinationHelper(rawDest, namedDest = null, explicitDest) {
+    // Dest array looks like that: <page-ref> </XYZ|/FitXXX> <args..>
+    const destRef = explicitDest[0];
+    let pageNumber;
 
-        if (pageNumber === null) {
+    if (destRef instanceof Object) {
-          // Fetch the page reference if it's not yet available. This could
+      pageNumber = this._cachedPageNumber(destRef);
-          // only occur during loading, before all pages have been resolved.
-          this.pdfDocument
-            .getPageIndex(destRef)
-            .then(pageIndex => {
-              this.cachePageRef(pageIndex + 1, destRef);
-              goToDestination({ namedDest, explicitDest });
-            })
-            .catch(() => {
-              console.error(
-                `PDFLinkService.navigateTo: "${destRef}" is not ` +
-                  `a valid page reference, for dest="${dest}".`
-              );
-            });
-          return;
-        }
-      } else if (Number.isInteger(destRef)) {
-        pageNumber = destRef + 1;
-      } else {
-        console.error(
-          `PDFLinkService.navigateTo: "${destRef}" is not ` +
-            `a valid destination reference, for dest="${dest}".`
-        );
-        return;
-      }
-      if (!pageNumber || pageNumber < 1 || pageNumber > this.pagesCount) {
-        console.error(
-          `PDFLinkService.navigateTo: "${pageNumber}" is not ` +
-            `a valid page number, for dest="${dest}".`
-        );
-        return;
-      }
 
-      if (this.pdfHistory) {
+      if (pageNumber === null) {
-        // Update the browser history before scrolling the new destination into
+        // Fetch the page reference if it's not yet available. This could
-        // view, to be able to accurately capture the current document position.
+        // only occur during loading, before all pages have been resolved.
-        this.pdfHistory.pushCurrentPosition();
+        this.pdfDocument
-        this.pdfHistory.push({ namedDest, explicitDest, pageNumber });
+          .getPageIndex(destRef)
-      }
+          .then(pageIndex => {
-
+            this.cachePageRef(pageIndex + 1, destRef);
-      this.pdfViewer.scrollPageIntoView({
+            this._goToDestinationHelper(rawDest, namedDest, explicitDest);
-        pageNumber,
+          })
-        destArray: explicitDest,
+          .catch(() => {
-        ignoreDestinationZoom: this._ignoreDestinationZoom,
+            console.error(
-      });
+              `PDFLinkService._goToDestinationHelper: "${destRef}" is not ` +
-    };
+                `a valid page reference, for dest="${rawDest}".`
-
+            );
-    new Promise((resolve, reject) => {
-      if (typeof dest === "string") {
-        this.pdfDocument.getDestination(dest).then(destArray => {
-          resolve({
-            namedDest: dest,
-            explicitDest: destArray,
           });
-        });
         return;
       }
-      resolve({
+    } else if (Number.isInteger(destRef)) {
-        namedDest: "",
+      pageNumber = destRef + 1;
-        explicitDest: dest,
+    } else {
-      });
+      console.error(
-    }).then(data => {
+        `PDFLinkService._goToDestinationHelper: "${destRef}" is not ` +
-      if (!Array.isArray(data.explicitDest)) {
+          `a valid destination reference, for dest="${rawDest}".`
-        console.error(
+      );
-          `PDFLinkService.navigateTo: "${data.explicitDest}" is` +
+      return;
-            ` not a valid destination array, for dest="${dest}".`
+    }
-        );
+    if (!pageNumber || pageNumber < 1 || pageNumber > this.pagesCount) {
-        return;
+      console.error(
-      }
+        `PDFLinkService._goToDestinationHelper: "${pageNumber}" is not ` +
-      goToDestination(data);
+          `a valid page number, for dest="${rawDest}".`
+      );
+      return;
+    }
+
+    if (this.pdfHistory) {
+      // Update the browser history before scrolling the new destination into
+      // view, to be able to accurately capture the current document position.
+      this.pdfHistory.pushCurrentPosition();
+      this.pdfHistory.push({ namedDest, explicitDest, pageNumber });
+    }
+
+    this.pdfViewer.scrollPageIntoView({
+      pageNumber,
+      destArray: explicitDest,
+      ignoreDestinationZoom: this._ignoreDestinationZoom,
     });
   }
 
+  /**
+   * This method will, when available, also update the browser history.
+   *
+   * @param {string|Array} dest - The named, or explicit, PDF destination.
+   */
+  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.goToDestination: "${explicitDest}" is not ` +
+          `a valid destination array, for dest="${dest}".`
+      );
+      return;
+    }
+    this._goToDestinationHelper(dest, namedDest, explicitDest);
+  }
+
   /**
    * @param {string|Array} dest - The PDF destination object.
    * @returns {string} The hyperlink to the PDF object.
@@ -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;
     };