Prerender EAGERNERSS

src/index.mjs

@@ -15,7 +15,7 @@
  **/
 
 import throttle from 'throttles';
-import {supported, viaFetch} from './prefetch.mjs';
+import {prefetchOnHover, supported, viaFetch} from './prefetch.mjs';
 import requestIdleCallback from './request-idle-callback.mjs';
 import {addSpeculationRules, hasSpecRulesSupport} from './prerender.mjs';
 
@@ -74,6 +74,7 @@ function checkConnection(conn) {
  * @param {Boolean} [options.priority] - Attempt higher priority fetch (low or high)
  * @param {Boolean} [options.checkAccessControlAllowOrigin] - Check Access-Control-Allow-Origin response header
  * @param {Boolean} [options.checkAccessControlAllowCredentials] - Check the Access-Control-Allow-Credentials response header
+ * @param {Boolean} [options.onlyOnMouseover] - Enable the prefetch only on mouseover event
  * @param {Array} [options.origins] - Allowed origins to prefetch (empty allows all)
  * @param {Array|RegExp|Function} [options.ignores] - Custom filter(s) that run after origin checks
  * @param {Number} [options.timeout] - Timeout after which prefetching will occur
@@ -86,6 +87,7 @@ function checkConnection(conn) {
  * @param {Function} [options.hrefFn] - Function to use to build the URL to prefetch.
  *                                             If it's not a valid function, then it will use the entry href.
  * @param {Boolean} [options.prerender] - Option to switch from prefetching and use prerendering only
+ * @param {String} [options.eagerness] - Prerender eagerness mode - default immediate
  * @param {Boolean} [options.prerenderAndPrefetch] - Option to use both prerendering and prefetching
  * @return {Function}
  */
@@ -135,7 +137,7 @@ export function listen(options = {}) {
           // either it's the prerender + prefetch mode or it's prerender *only* mode
           // Prerendering limit is following options.limit. UA may impose arbitraty numeric limit
           if ((shouldPrerenderAndPrefetch || shouldOnlyPrerender) && toPrerender.size < limit) {
-            prerender(hrefFn ? hrefFn(entry) : entry.href).catch(error => {
+            prerender(hrefFn ? hrefFn(entry) : entry.href, options.eagerness).catch(error => {
               if (options.onError) {
                 options.onError(error);
               } else {
@@ -150,7 +152,7 @@ export function listen(options = {}) {
           if (toPrefetch.size < limit && !shouldOnlyPrerender) {
             toAdd(() => {
               prefetch(hrefFn ? hrefFn(entry) : entry.href, options.priority,
-                  options.checkAccessControlAllowOrigin, options.checkAccessControlAllowCredentials)
+                  options.checkAccessControlAllowOrigin, options.checkAccessControlAllowCredentials, options.onlyOnMouseover)
                   .then(isDone)
                   .catch(error => {
                     isDone();
@@ -208,9 +210,10 @@ export function listen(options = {}) {
 * @param {Boolean} checkAccessControlAllowOrigin - true to set crossorigin="anonymous" for DOM prefetch
 *                                                    and mode:'cors' for API fetch
 * @param {Boolean} checkAccessControlAllowCredentials - true to set credentials:'include' for API fetch
+* @param {Boolean} onlyOnMouseover - true to enable prefetch only on mouseover event
 * @return {Object} a Promise
 */
-export function prefetch(urls, isPriority, checkAccessControlAllowOrigin, checkAccessControlAllowCredentials) {
+export function prefetch(urls, isPriority, checkAccessControlAllowOrigin, checkAccessControlAllowCredentials, onlyOnMouseover) {
   const chkConn = checkConnection(navigator.connection);
   if (chkConn instanceof Error) {
     return Promise.reject(new Error(`Cannot prefetch, ${chkConn.message}`));
@@ -229,7 +232,7 @@ export function prefetch(urls, isPriority, checkAccessControlAllowOrigin, checkA
         // ~> so that we don't repeat broken links
         toPrefetch.add(str);
 
-        return (isPriority ? viaFetch : supported)(new URL(str, location.href).toString(),
+        return prefetchOnHover((isPriority ? viaFetch : supported), new URL(str, location.href).toString(), onlyOnMouseover,
             checkAccessControlAllowOrigin, checkAccessControlAllowCredentials, isPriority);
       }),
   );
@@ -238,9 +241,10 @@ export function prefetch(urls, isPriority, checkAccessControlAllowOrigin, checkA
 /**
 * Prerender a given URL
 * @param {String | String[]} urls - the URLs to fetch
+* @param {String} eagerness - prerender eagerness mode - default immediate
 * @return {Object} a Promise
 */
-export function prerender(urls) {
+export function prerender(urls, eagerness = 'immediate') {
   const chkConn = checkConnection(navigator.connection);
   if (chkConn instanceof Error) {
     return Promise.reject(new Error(`Cannot prerender, ${chkConn.message}`));
@@ -250,7 +254,7 @@ export function prerender(urls) {
   // 1) whether UA supports spec rules.. If not, fallback to prefetch
   // Note: Prerendering supports same-site cross origin with opt-in header
   if (!hasSpecRulesSupport()) {
-    prefetch(urls, true, false, false);
+    prefetch(urls, true, false, false, eagerness === 'moderate' || eagerness === 'conservative');
     return Promise.reject(new Error('This browser does not support the speculation rules API. Falling back to prefetch.'));
   }
 
@@ -263,6 +267,6 @@ export function prerender(urls) {
     console.warn('[Warning] You are using both prefetching and prerendering on the same document');
   }
 
-  const addSpecRules = addSpeculationRules(toPrerender);
+  const addSpecRules = addSpeculationRules(toPrerender, eagerness);
   return addSpecRules === true ? Promise.resolve() : Promise.reject(addSpecRules);
 }

src/prefetch.mjs

@@ -101,4 +101,41 @@ export function viaFetch(url, hasModeCors, hasCredentials, isPriority) {
   return window.fetch ? fetch(url, options) : viaXHR(url, hasCredentials);
 }
 
+/**
+ * Calls the prefetch function immediately
+ * or only on the mouseover event.
+ * @param {Function} callback  - original prefetch function
+ * @param {String} url - url to prefetch
+ * @param {Boolean} onlyOnMouseover - true to add the mouseover listener
+ * @return {Object} a Promise
+ */
+export function prefetchOnHover(callback, url, onlyOnMouseover, ...args) {
+  if (!onlyOnMouseover) return callback(url, ...args);
+
+  const elements = Array.from(document.querySelectorAll('a')).filter(el => el.href === url);
+  const timerMap = new Map();
+
+  for (const el of elements) {
+    const mouseenterListener = _ => {
+      const timer = setTimeout(() => {
+        el.removeEventListener('mouseenter', mouseenterListener);
+        el.removeEventListener('mouseleave', mouseleaveListener);
+        return callback(url, ...args);
+      }, 200);
+      timerMap.set(el, timer);
+    };
+
+    const mouseleaveListener = _ => {
+      const timer = timerMap.get(el);
+      if (timer) {
+        clearTimeout(timer);
+        timerMap.delete(el);
+      }
+    };
+
+    el.addEventListener('mouseenter', mouseenterListener);
+    el.addEventListener('mouseleave', mouseleaveListener);
+  }
+}
+
 export const supported = hasPrefetch() ? viaDOM : viaFetch;

src/prerender.mjs

@@ -23,10 +23,12 @@
  * @param {String} eagerness - prerender eagerness mode
  * @return {Boolean|Object}  boolean or Error Object
  */
-export function addSpeculationRules(urlsToPrerender) {
+export function addSpeculationRules(urlsToPrerender, eagerness) {
   const specScript = document.createElement('script');
   specScript.type = 'speculationrules';
-  specScript.text = `{"prerender":[{"source": "list","urls": ["${Array.from(urlsToPrerender).join('","')}"]}]}`;
+  specScript.text = `{"prerender":[{"source": "list",
+                      "urls": ["${Array.from(urlsToPrerender).join('","')}"],
+                      "eagerness": "${eagerness}"}]}`;
   try {
     document.head.appendChild(specScript);
   } catch (error) {